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内 容 提 要 


本 书 依 托 ASP.NET Web API 阐述 API 设计 与 开发 的 通用 技术 ， 是 一 本 全 面 介绍 如 何 构建 真 
实 可 演化 API 的 实践 指南 。 本 书 共 分 三 部 分 。 第 一 部 分 介绍 Web/HTTP 和 API 开 发 的 基础 知识 ， 
介绍 ASPNET Web API， 为 初学 者 以 及 想 充 分 利用 HTTP 的 读者 建立 好 的 起 点 。 第 二 部 分 完整 
介绍 了 真实 Web 应 用 程序 的 开发 ， 其 内 容 从 设计 讲 到 实现 ， 全 面 履 盖 客户 端 与 服务 器 端 开 发 。 第 
三 部 分 深入 ASP.NET Web API 的 内 部 机 制 ， 并 讲解 一 些 高 级 的 主题 (如 安全 和 可 测试 性 )， 加 深 
你 的 理解 ， 让 读者 学 会 更 好 地 利用 Web API 构建 可 演化 系统 。 

本 书 适合 使 用 .NET、Java、Ruby、PHP、Node 等 各 平台 API 的 开发 人 员 学 习 参 考 。 
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BE} 


分 布 于 


下 生长 一 段 时 间 ， 在 四 个 月 大 时 经 历 晓 变 ， 


大 于 封面 图 








A LA shee veEW (学 名 Triturus cristatus) ， 又 名 

















北 晨 或 巨 冠 蝶 蚌 。 这 种 两 栖 动 物 


欧洲 北部 ， 从 英国 一 直到 黑 海 。 疣 央 是 生活 在 不 列 颠 群岛 上 的 三 种 蝶 晨 中 最 大 最 稀 
有 的 一 种 ， 在 当地 受到 生物 多 样 性 行动 计划 的 保护 。 生 物 多 样 性 行动 计划 致力 于 将 沽 危 物 
种 进行 统计 并 形成 保护 计划 。 
疣 颗 大 部 分 时 间 呆 在 陆地 上 ， 但 是 会 回 到 池塘 中 进行 繁殖 。 幼 虫 大 约 三 周 后 孵化 ， 并 在 水 























成 为 呼吸 空气 的 青年 疣 颗 ， 离 开 池 塘 上 岸 居 





住 。 在 陆地 上 ， 王 晨 捕 食 昆虫 及 其 幼虫 。 成 年 更 昧 还 会 在 池塘 中 捕食 其 他 蝶 蚌 、 师 昨 、 幼 
年 青蛙 、 昆 虫 或 田螺 。 














因 其 防御 能 力 相 对 较 弱 ， 疣 晨 喜 欢 居住 在 有 植被 履 盖 的 辕 








i 地 上 上 ， 例 如 灌木 从 、 草 从 和 成 密 


的 丛林 。 趴 性 疣 果 体 积 比 奴 性 大 ， 长 度 可 以 达到 15 EX. AEE AE PEE Wt AR FH TY 








颜色 医 











LE HEW 10 月 到 3 AKIR, DCE SR oH tS eR BUA VE A ARAL ALK TM. 


案 : 背部 和 侧面 为 深 灰 到 黑色 ， 腹 部 为 黄色 或 橘红 色 ， 并 有 墨色 斑点 。 在 繁殖 期 ， 
REEVE DCM BBE HAIRS, SIME PEE PULA Ta 








通常 ， 











疣 晨 每 年 都 返回 同一 个 葡 殖 地 ， 一 般 不 会 离开 出 生地 半 英 里 的 冰 围 。 虽 然 有 些 疣 虹 可 以 活 
30 年 之 入 ， 但 是 在 野外 大 部 分 只 能 存活 约 10 年 。 
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1989 年 3 月 ， 当 Tim Berners-Lee 在 欧洲 核子 研究 组 织 (CERN, http://info.cern.ch/) 首次 提 
出 Web 的 概念 Chttp://www.w3.org/History/1989/proposal.html) 时 ， 就 引发 了 一 场 创造 性 和 机 
仙 的 社交 革命 。 这 场 革 命 从 此 横扫 人 全球， 改变 了 社会 的 运作 方式 和 人 们 的 交互 方式 ， 也 改变 
了 我 们 如 何 看 待 自己 作为 个 体 在 社会 中 承担 的 角色 。 


但 是 ，Berners-Lee 还 引发 了 一 场 影响 同样 深远 的 技术 革命 ， 改 变 了 工程 师 们 为 Web 设计 思 
考 和 构建 软 硬 件 系统 的 方式 。Web 服务 器 的 概念 从 单个 计算 机 变 成 了 全 球 云端 基础 设施 中 一 
个 完全 虚拟 的 部 分 。 在 云端 ， 我 们 可 以 在 任何 需要 的 地 方 进行 计算 。 同 样 ，Web 客户 端 也 从 
传统 的 安装 了 浏览 器 的 果 面 个 人 电脑 ， 变 成 了 无 数 可 以 感知 物理 世界 并 与 之 交互 的 设备 ， 这 
些 设备 通过 云端 的 Web 服务 器 与 其 他 设备 相连 。 
























































如 果 我 们 想 想 Web 经 历 的 变化 ， 油 动人 心 的 不 仅仅 是 这 些 变化 发 生 的 令 人 目 上 及 的 速度 ， 还 
在 于 这 些 变化 的 发 生 没有 任何 集中 的 控制 或 协调 。 也 就 是 说 ，Web 经 历 的 是 演化 。 为 了 适应 
新 的 需求 ， 新 的 想法 和 解决 方案 不 断 涌现 ， 与 旧 想 法 进行 竞争 。 有 时 候 ， 新 想法 胜出 ， 存 活 
下 来 ， 有 了 时候， 新 想法 落 败 ， 自 行 消亡 。 


演化 天 生 就 是 Web 不 可 或 缺 的 一 部 分 。 和 大 自然 的 演化 一 样 ， 如 果 Web 中 的 某 些 组 件 适 应 
变化 的 能 力 较 强 ， 就 更 有 机 会 保持 活力 ， 不 断 发 展 。 




















不 仅 Web 服务 器 和 客户 端 发 生 了 变化 ， 服 务 器 和 客户 端 之 间 的 交互 方式 也 在 发 生 巨大 的 改 
变 。 过 去 ，Web 服务 器 提供 HTML， 由 客户 端 展 示 为 Web WH; Kb, Web 客户 端 将 
HTML 表单 提交 给 服务 器 处 理 ， 无 论 是 处 理 比 萨 饼 订单 ， 播 入 一 篇 博客 文章 ， 还 是 更 新 缺陷 
管理 系统 中 的 一 个 问题 。 











这 种 交互 模型 主要 使 用 GET Fu post 方法， 实际 上 只 用 到 了 HTTP 的 一 部 分 功能 。 但 是 ， 
HTTP 从 一 开始 就 定义 了 一 个 范围 更 广 的 应 用 程序 模型 ， 全 面 支持 与 数据 的 交互 和 对 数据 的 
操控 。 例 如 : Ws FAS cet FN Post 方法 ，HTTP 还 定义 了 PUT、DELETE 和 PATCH 方法 ， 可 
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以 编程 操控 资产， 并 与 资源 进行 交互 。 

















这 就 是 我 们 用 到 Web API 的 地 方 : 利用 Web API, Web 服务 器 可 以 提供 完整 的 HTTP 应 用 
程序 模型 ， 支 持 对 资源 的 编程 访问 ， 使 客户 端 能 够 在 多 种 不 同情 况 下 ， 以 一 致 的 方式 与 数据 
进行 交互 ， 并 对 其 进行 操控 。 


推动 人 们 转向 Web API 的 关键 因素 有 两 个 : HTMLS 和 移动 应 用 。HTML5 和 移动 应 用 都 利 
用 客户 端 平台 的 计算 能 力 ， 提 供 引 人 入 胜 的 流畅 体验 ， 同 时 通过 后 台 Web API 获取 和 操控 
数据 。 概 括 地 说 ， 过 去 Web 服务 器 只 提供 静态 HTML， 而 现在 也 提供 Web API， 因 此 客户 
端 可 以 使 用 HTTP 应 用 程序 模型 的 全 部 功能 ， 进 行程 序 化 交互 。 这 本 书 要 解决 的 问题 ， 就 
是 如 何 构建 出 这 样 的 Web API。 简 言 之 ,任何 人 要 构建 针对 HTMLS 应 用 程序 以 及 移动 应 用 
的 Web API， 都 应 该 读 一 读本 书 。 本 书 不 仅 很 好 地 介绍 了 Web API， 还 提供 很 多 实用 指南 ， 
指导 大 家 使 用 ASP.NET Web API 构建 Web API。 此 外 ， 本 书 还 详尽 地 介绍 了 ASP.NET Web 
API 的 工作 原理 。 你 也 可 以 以 本 书 为 参考 ， 了 解 如 何 通过 HTTP 消息 处 理 程序 、 格 式 化 程序 
等 ， 对 ASP.NET Web API 进行 扩展 。 























本 书 不 仅 包 括 代 码 展 示 和 框架 说 明 ， 还 介绍 了 一 些 强 大 的 技术 ， 例 如 : TDD (Test-Driven 
Development， 测 试 驱 动 开发 ) 和 BDD (Behavior-Driven Development， 行 为 驱动 开发 )， 帮 
助 你 编写 应 用 程序 ， 并 测试 、 验 证 程序 功能 是 否 符合 预期 。 


更 棒 的 是 ， 本 书 不 仅 提 供 了 关于 如 何 构 建 Web API 的 “当前 ”指南 ， 还 引导 你 逐步 了 解 如 何 
设计 一 个 随 着 需求 和 约束 变化 演化 的 Web API。 解 决 可 演化 性 问题 的 想法 渗透 到 了 Web 运 
作 方 式 的 核心 。 


在 这 种 环境 下 构建 一 个 有 效 运行 的 Web API 并 非 易 事 。 但 有 一 点 很 明确 ， 你 必须 从 一 开始 
就 接受 一 个 观点 : 任何 Web API 都 必 将 发 生 改 变 ， 而 且 没 有 人 能 在 某 一 时 刻 控 制 环境 中 的 
所 有 因素 。 也 就 是 说 ， 如 果 你 设计 了 系统 的 一 个 新 版 本 ， 就 把 旧版 本 抛弃 ， 那 么 必定 会 失去 
已 有 用 户 或 者 导致 问题 一 一 你 必须 逐步 对 系统 进行 改进 ， 既 要 继续 支持 旧 客 户 端 ， 同 时 又 要 
向 新 客户 端 提供 新 功能 。 


但 是 ， 构 建 一 个 灵活 的 可 演化 软件 仍然 是 个 难题 。 本 书 极 佳 地 阐述 了 如 何 构建 可 以 随 着 需求 
变更 和 演化 的 现代 Web 应 用 程序 ， 其 介绍 方式 是 将 Web API 与 超 媒体 结合 ， 这 是 Web 应 用 
程序 的 一 个 激动 人 心 的 新 方向 。 


超 媒体 既是 一 个 新 概念 ， 也 是 一 个 旧 概念 。 我 们 都 惯 于 浏览 Web 页 面 ， 寻 找 信息 ， 然 后 点 
击 一 个 链接 ， 打 开 新 的 页 面 ， 获 得 更 多 的 信息 和 链接 ， 深 入 了 解 感 兴趣 的 方面 。 随 着 信息 发 
生 改 变 或 演化 ，Web 页 面 可 以 加 入 新 链接 ， 或 者 修改 已 有 链接 以 反映 这 些 变 化 。 这 些 新 链接 
可 以 为 你 提供 新 信息 ， 深 入 更 多 的 领域 。 





















































将 Web API 与 超 媒 体 相 结 合 ， 你 将 得 到 一 个 强大 的 模型 ， 应 用 程序 可 以 像 Web 页 面 一 样 变 
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化 ， 适 应 和 调整 程序 与 服务 器 交互 的 方式 。 现 在 ， 客 户 端 不 再 有 固定 的 操作 流程 ， 而 是 根据 
可 用 的 链接 修改 自己 的 行为 ， 以 进行 演化 ， 简 言 之 ， 客 户 端 能 够 适应 变化 。 























对 此 ， 本 书 提供 了 一 个 全 面 的 概览 ， 介 绍 设计 可 适应 双方 (提供 商 和 消费 者 ) 需求 变化 的 
Web API 的 最 先进 方法 。 通 过 介绍 相关 概念 ， 例 如 使 用 测试 驱动 开发 构建 超 媒 体 驱 动 的 Web 
API， 本 书 为 需要 构建 Web API 的 开发 者 提供 了 一 个 很 好 的 起 点 。 


作为 ASP.NET Web API 开 发 团队 的 一 员 ， 我 很 高 兴 与 本 书 的 作者 一 起 工作 。 本 书 的 作者 非 
常 优秀 ， 他 们 不 但 都 具有 构建 框架 的 经 验 ， 而 且 拥 有 构建 基于 HTTP 概念 的 实际 系统 的 丰富 
实战 经 验 。 本 书 的 作者 提出 了 很 多 极 有 价值 的 意见 和 建议 ， 帮 助 ASP.NET Web API 成 为 构 
建 现代 Web 应 用 程序 的 流行 框架 。 




















我 与 Glenn Block 的 合作 特别 愉快 ，Block 很 早 就 加 入 了 ASP.NET Web API 项 目 ， 极 大 推动 
了 项 目 对 社区 参与 的 重视 ， 以 及 对 依赖 注入 、 测 试 驱 动 开发 和 超 媒体 重要 性 的 认识 。 没 有 
Block 的 贡献 ，ASP.NET Web API 就 不 会 达到 今天 的 高 度 。 





如 果 你 正在 或 者 考虑 构建 Web API， 那 么 本 书 不 仅 可 以 作为 一 个 学 习 工 具 ， 而 且 可 以 用 作 实 
际 的 指南 ， 帮 助 你 基于 ASP.NET Web API 构建 现代 Web 应 用 程序 。 本 书 提供 了 大 量 的 信息 
和 指导 原则 ， 将 教 你 以 一 种 新 颖 的 方式 看 待 复杂 问题 ， 在 设计 中 时 刻 考 虑 可 演化 性 。 我 自己 
非常 期 待 看 到 本 书 在 未 来 如 何 演 化 ! 








Henrick Frystyk Nielsen 
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为 什么 要 阅读 本 书 

Web API 开 发 呈现 爆炸 式 增 长 。 各 家 公司 都 在 投资 构建 可 以 通过 Web 使 用 多 种 客户 端 访 
问 的 系统 。 想 想 你 经 常 光顾 的 网 站 ， 这 些 网 站 很 可 能 已 经 提供 了 访问 API。 创 建 一 个 使 用 
HTTP 进行 通信 的 API 非常 简 单 ， 而 挑战 在 第 一 个 版 本 部 署 后 才 会 出 现 。 实 际 上 ，HITP 
协议 的 制定 者 对 这 个 问题 ， 以 及 如 何 设计 可 演化 API 已 经 进行 了 周详 的 考虑 。 媒 体 类 型 和 
超 媒 体 就 是 设计 可 演化 API 的 核心 。 但 是 ， 很 多 API 开发 者 并 未 对 此 加 以 考虑 或 利用 ， 部 
署 的 API 没有 合理 地 使 用 HTTP 协议 ， 客 户 端 严重 依赖 API 的 具体 实现 。 这 样 的 API 很 
难 进 行 演化 ， 极 易 破 坏 客户 端 功能 。 为 什么 会 出 现 这 样 的 情况 呢 ? 因为 人 们 经 常 觉得 ， 从 
工程 角度 看 ， 这 是 实现 功能 的 最 简单 、 最 直接 的 做 法 。 但 是 ， 从 长 期 看 ， 这 种 做 法 违反 直 
te, 4 Web 自身 的 基本 设计 原则 背道而驰 。 


























本 书 的 目标 读者 是 希望 设计 出 适应 长 期 变化 的 API 的 开发 者 。 变 化 是 不 可 避免 的 : 你 今天 
构建 的 API 将 会 演化 。 因 此 ， 问 题 不 是 “要 不 要 ”， 而 是 “如 何 ” 设 计 可 演化 的 API。 你 
在 项 目 早期 做 出 的 决定 (或 者 未 做 出 的 决定 ) 会 极 大 地 影响 以 下 问题 的 答案 。 


。 添加 一 个 新 功能 , 会 破坏 现 有 的 客户 端 , 强制 现 有 客户 端 升级 并 重新 部 署 吗 ? 或 者 ， 
现 有 客户 端 还 能 继续 工作 ? 

。 如 何 保障 API 的 安全 ? 能 够 使 用 较 新 的 安全 协议 吗 ? 

。 API 可 以 扩展 规模 ， 满 足 用 户 需求 吗 ?或 者 必须 重新 进行 架构 设计 ? 

。 能 够 支持 未 来 出 现 的 新 客户 端 和 新 设备 吗 ? 


你 在 设计 时 可 以 考虑 这 些 问 题 。 初 看 起 来 ， 这 似乎 是 预先 做 大 量 设计 (Big Design Up Front) 
或 者 瀑布 方法 。 其 实 不 然 。 你 不 需要 在 构建 系统 前 做 出 完备 的 设计 ， 也 不 需要 进行 过 度 分 
析 。 有 些 决定 的 确 需 要 预先 做 出 ， 但 这 些 决 定 处 于 较 高 的 层次 ， 关 系 到 整体 设计 。 要 做 出 
这 些 决定 ， 你 并 不 需要 理解 或 预知 系统 的 每 个 方面 。 实 际 上 ， 这 些 决 定 黄 定 了 友 代 演化 的 
































XX 


基础 ， 在 随后 构建 系统 时 ， 你 可 以 在 此 基础 上 ， 采 取 各 种 方式 不 断 强 化 自己 的 目标 。 


本 书 更 偏重 应 用 而 非 理 论 。 我 们 希望 你 读 完 本 书 之 后 ， 获 得 构建 真实 可 演化 系统 的 能 
为 了 达到 这 个 目的 ， 开 篇 将 介绍 Web 和 Web API 开发 的 一 些 必 知 内 容 ， 然 后 从 设计 到 实 
现 ， 逐 步 介 绍 如 何 使 用 ASP.NET Web API 创建 一 个 新 API。 这 个 API 的 实现 将 覆盖 一 些 
重要 的 主题 ， 例 如 : 如 何 使 用 ASP.NET Web API 实现 超 媒体 、 如 何 执行 内 容 协 商 。 我 们 
将 演示 这 个 API 在 部 署 后 如 何 实际 进行 演化 ， 还 将 讨论 如 何 使 用 既 有 实践 〈 例 如 : 验收 测 
试 、 测 试 驱 动 开 发 ) 和 技术 (例如; 控制 反 转 ) 提高 代码 的 可 维护 性 。 最 后 ， 我 们 将 深入 
Web API 的 内 部 ， 帮 助 你 加 次 理解 ， 更 好 地 利用 Web API 构建 可 演化 系统 。 


预备 知识 


要 充分 理解 本 书 的 内 容 ， 你 应 该 是 一 位 开发 人 员 ， 拥 有 使 用 NET 3.5 或 更 高 版 本 开发 CH 
应 用 程序 的 经 验 。 如 果 你 还 具有 构建 Web API 的 经 验 ， 那 就 更 好 了 。 在 开发 API 时 使 用 过 
哪 种 框架 并 不 重要 ， 重 要 的 是 应 该 熟悉 相关 的 概念 。 阅 读本 书 并 不 需要 ASP.NET Web API 
或 ASP.NET 经 验 ， 但 熟悉 ASP.NET MVC 的 确 会 对 你 很 有 帮助 。 









































如 有 果 你 不 是 一 位 .NET 开发 人 员 ， 那 么 本 书 也 有 适合 阅读 的 内 容 。 我 们 编写 本 书 时 设 定 了 
一 个 具体 的 目标 ， 要 使 书 中 大 部 分 内 容 关 注 API 设计 和 开发 的 通用 技术 ， 不 与 ASP.NET 
Web API 直接 相关 。 因 此 ， 我 们 认为 ， 无 论 你 的 开发 背景 是 什么 (Java, Ruby, PHP, 
Node 等 )， 都 可 以 通过 本 书 前 两 部 分 的 大 部 分 内 容 学 习 API 的 开发 。 


漫游 指南 


在 开始 你 的 阅读 旅程 之 前 ， 这 里 有 一 些 漫 游 本 书 内 容 的 指南 。 











第 一 部 分 主要 对 Web API 开 发 进行 介绍 。 这 部 分 覆盖 了 Web/HTTP Fil API 开发 
的 基础 知识 ， 介 绍 ASP.NET Web API。 如 果 你 刚刚 接触 Web API 开发 /ASP.NET 
Web APL, 那 么 这 部 分 是 一 个 很 好 的 开始 。 如 果 你 已 经 在 使 用 ASP.NET Web API( 或 
其 他 Web API 框架 )， 但 是 想 更 多 地 了 解 如 何 充分 利用 HTTP， 这 部 分 也 是 一 个 很 
好 的 起 点 。 

第 二 部 分 关注 真实 世界 的 Web API 开发 。 这 部 分 完整 介绍 了 一 个 真实 世界 中 Web 
应 用 程序 的 开发 ， 从 设计 到 实现 ， 履 盖 客 户 端 和 服务 器 。 如 果 你 已 经 对 Web API 
开发 颇 为 熟悉 ， 希 望 很 快 开始 构建 应 用 程序 ， 那 么 可 以 直接 从 第 二 部 分 开始 阅读 。 
第 三 部 分 是 一 个 相当 全 面 的 参考 资料 ， 详 细 介绍 了 ASP.NET Web API 各 部 分 的 内 
部 机 制 。 这 部 分 还 覆盖 了 一 些 较为 高 级 的 主题 ， 例 如 : 安全 和 可 测试 性 。 如 果 你 已 
经 在 使 用 ASP.NET Web API 构建 应 用 程序 ， 和 希望 了 解 如 何 将 Web API 自身 的 功能 
发 挥 到 极致 ， 请 从 第 三 部 分 开始 阅读 。 














本 书 内 容 


本 书 分 为 三 部 分 。 


第 一 部 分 ”基础 知识 


。 第 1 章 因特网 、 万 维 网 和 HTTP 协议 
这 一 章 开篇 简单 回顾 了 万 维 网 和 HTTP 协议 的 历史 ， 然 后 概要 介绍 了 HTTP 协议。 你 
以 把 这 一 章 看 成 HTTP“ 傻 瓜 指南 ”"。 这 一 章 提 供 了 你 需要 了 解 的 关键 知识 ， 以 免 去 你 
阅读 整个 HTTP 规范 的 辛苦 。 











。 第 2 章 Web API 
这 一 章 首先 大 致 介绍 了 Web API 开 发 的 历史 背景 ， 然 后 讨论 API 开发 的 精髓 ， 从 核心 
概念 开始 ， 一 直 深入 探讨 到 设计 API 的 风格 和 方法 。 





。 第 3 章 ASP.NET Web API 基 础 


这 一 章 讨论 了 ASP.NET Web API 框架 背后 的 基本 驱动 因素 ， 然 后 介绍 ASP.NET Web 
API 的 基础 知识 ， 以 及 NET HTTP 编程 模型 和 客户 端 。 











。 RAF ”处 理 架构 
这 一 章 将 简要 介绍 一 个 HTTP 请 求 在 ASP.NET Web API 中 进行 处 理 的 生命 周期 。 你 将 
了 解 到 处 理 HTTP 请 求 和 响应 的 不 同方 面 涉 及 的 各 个 不 同 部 分 。 














第 二 部 分 真实 世界 的 API 开 发 


。 第 5 章 应 用 程序 + 第 6 章 媒 体 类 型 选择 与 设计 
这 两 章 讨论 了 问题 跟踪 应 用 程序 的 整体 设计 ， 涵 盖 了 设计 相关 的 儿 个 重要 主题 ， 其 中 
有 : 媒体 类 型 选择 和 设计 ， 以 及 超 媒 体 。 


。 第 7 章 构建 API+ 第 8 章 AH API 
这 两 章 展示 了 如 何 使 用 ASP.NET Web API 实现 和 改进 超 媒体 驱动 的 问题 跟踪 API， 并 
介绍 了 如 何 使 用 行为 驱动 的 开发 方式 。 





ky 


。 POR WERP H 
这 一 章 介绍 如 何 构建 问题 跟踪 API 的 一 个 超 媒体 客户 端 。 








第 三 部 分 Web API 细 节 


第 10 章 HTTP 编程 模型 
一 章 将 深入 讨论 ASP.NET Web API 依托 的 .NET HTTP 编程 新 模型 。 


第 11 章 托管 
这 一 章 介 绍 了 ASP.NET Web API 适用 的 所 有 托管 模型 ， 其 中 有 : 自 托 管 、IIS 以 及 新 的 
OWIN 模型 。 


第 12 章 控制 器 和 路 由 
这 一 章 深 入 探讨 了 Web API 路 由 的 工作 机 制 ， 以 及 控制 器 如 何 运作 。 


3 章 格式 化 程序 和 模型 绑 定 /第 14 章 HttpClient 
这 两 章 介绍 了 关于 模型 绑 定 和 使 用 新 的 HTTP 客户 端 类 的 所 有 需 知 内 容 。 


第 15 章 安全 /第 16 章 OAuth 2.0 授权 框架 
这 两 章 介绍 了 ASP.NET Web API 的 整体 安全 模型 ， 然 后 详细 讨论 了 如 何在 API 中 实现 
OAuth 规范 。 





7 章 可 测试 性 
一 章 将 介绍 如 何以 测试 驱动 的 方式 ， 在 ASP.NET Web API 中 进行 开发 。 





排版 约定 


本 书 使 用 了 下 述 排版 约定 。 


楷体 
标示 新 术语 。 





等 宽 字 体 (constant width ) 
表示 程序 片段 ， 也 用 于 在 正文 中 表示 程序 中 使 用 的 变量 、 函 数 名 、 命 令 行 代 码 、 环 境 变 
量 、 语 句 和 关键 字 等 元 素 。 





等 宽 粗 体 (constant width bold) 
表示 应 该 由 用 户 逐 字 输 入 的 命令 或 者 其 他 文本 。 


等 宽 斜 体 (constant width italic) 
表示 应 该 由 用 户 输入 的 值 或 根据 上 下 文 决定 的 值 禁 换 的 文本 。 
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Ill 





这 个 图 标 代表 提示 或 建议 。 








这 个 图 标 代表 重要 说 明 。 


Be 这 个 图 标 代表 警告 或 提醒 。 


使 用 代码 示例 


读者 可 以 在 这 里 下 载 本 书 随 附 的 资料 (代码 示例 、 练 习题 等 ) : https://github.com/ 
webapibook。 讨 论 本 书 的 论坛 地 址 为 : https://groups.google.com/forum/#!forum/webapibook。 














希望 本 书 能 够 助 你 一 臂 之 力 。 也 许 你 需要 在 自己 的 程序 或 文档 中 用 到 本 书 中 的 代码 。 除 非 
大 段 大 段 地 使 用 ， 否 则 你 不 必 与 我 们 联系 取得 授权 。 例 如 ， 无 需 请 求 许 可 ， 你 就 可 以 用 本 
书 中 的 几 段 代码 写成 一 个 程序 。 但 是 销售 或 者 发 布 OReilly 图 书 中 代码 的 光盘 则 必须 事先 
获得 授权 。 引 用 书 中 的 代码 来 回答 问题 也 无 需 获 得 授权 。 将 大 段 的 示例 代码 整合 到 你 自己 
的 产品 文档 中 则 必须 经 过 许可 。 

















使 用 我 们 的 代码 时 ， 希望 你 能 标明 它 的 出 处 ， 但 不 强求 。 出 处 一 般 包 括 书 名 、 作 者 、 出 
版 商 和 ISBN， 例 如 : Designing Evolvable Web APIs with ASP.NET by Glenn Block, Pablo 
Cibraro, Pedro Felix, Howard Dierking, Darrel Miller (O’Reilly). Copyright 2012 Glenn Block, 
Pablo Cibraro, Pedro Felix, Howard Dierking, and Darrel Miller, 978-1-449-33771-1., 




















如 果 还 有 关于 使 用 代码 的 未 尽 事宜 ， 你 可 以 随时 与 我 们 联系 : permissions @ oreilly.com, 
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1005 Gravenstein Highway North 
Sebastopol, CA 95472 
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北京 市 西城 区 西直门 南大 街 2 号 成 馈 大 厦 C 座 807 室 (100035) 
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O'Reilly 的 每 一 本 书 都 有 专属 网 页 ， 你 可 以 在 那儿 找到 本 书 的 相关 信息 ， 包 括 勘 误 表 、 示 
例 代 码 以 及 其 他 信息 。 本 书 的 网 站 地 址 是 : 
http://oreil.ly/designing-api 








如 果 你 对 本 书 有 一 些 建议 或 技术 上 的 疑问 ， 请 发 送 电 子 邮件 至 bookquestions@oreilly.com。 
要 了 解 更 多 O'Reilly 图 书 、 培 训 课 程 、 会 议和 新 闻 的 信息 ， 请 访问 以 下 网 站 : 


http://www.oreilly.com 


我 们 在 Facebook 的 地 址 如 下 : http://facebook.com/oreilly 
请 关注 我 们 的 Twitter 动态 : http://twitter.com/oreillymedia 
我 们 的 YouTube 视频 地 址 如 下 : http://www.youtube.com/oreillymedia 








完成 这 本 书 ， 实 际 的 工作 量 远 超 我 们 的 预计 。 首 先 要 感谢 我 们 的 妻子 和 孩子 ， 他 们 给 予 了 





我 们 大 量 的 耐心 ， 以 及 写作 的 时 间 和 空间 。 








如 果 没 有 大 家 的 审阅 和 指导 ， 我 们 不 可 能 完成 这 本 书 ， 在 此 要 感谢 : Mike Amundsen, 
Grant Archibald, Dominick Baier, Alan Dean, Matt Kerr, Caitie McCaffrey, Henrik Frystyk 


Nielsen, Eugenio Pace, Amy Palamountain, Adam Ralph, Leonard Richardson, Ryan 


Riley, Kelly Sommers, Filip Wojcieszyn 和 Matias Woloski。 
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因特网 、 万 维 网 和 HTTP 协 议 





要 掌握 Web， 就 要 理解 其 基础 和 设计 。 


让 我 们 从 源头 开始 了 解 Web API。 在 20 世纪 60 年 代 后 期 ，DARPA (Defense Advanced 
Research Projects Agency， 美 国 国防 部 高 级 研究 计划 局 ) 创建 了 以 TCP/IP 协议 连接 的 一 组 
基于 网 络 的 系统 ， 即 ARPANET (Advanced Research Projects Agency Network, http://www. 
cs.utexas.edu/users/chris/think/ARPANET/), ARPANET 的 设计 初衷 是 在 美国 的 大 学 和 实验 
室 中 共享 数据 (参见 图 1-1)。 























ARPANET LOGICAL MAP, MARCH 1977 





OTP aw SATELLITE CIRCUIT 


(PLEASE NOTE THAT WHILE THIS MAP SHOWS THE HOST POPULATION OF THE NETWORK ACCORDING TO THE BEST 
INFORMATION OBTAINABLE, NO CLAIM CAN BE MADE FOR ITS ACCURACY) 


NAMES SHOWN ARE IMP NAMES. NOT INECESSARILY) HOST NAMES 


B 1-1: ARPANET (图 片 来 自 维基 共享 资源 ) 











ARPANET 不 断 完 善 ， 终 于 在 1982 年 衍生 出 一 个 全 球 性 的 互联 网 络 ， 即 因特网 。 因 特 网 
建立 在 一 组 通信 协议 一 一 TCP/IP (Internet protocol suite， 因 特 网 协议 族 ) 的 基础 上 。 虽 然 
ARPANET 是 一 个 相当 封闭 的 系统 ， 但 因特网 被 设计 为 一 个 全 球 性 的 开放 系统 ， 以 连接 公 
私 单 位 、 组 织 、 机 构 及 个 人 。 











在 1989 年 ， 欧 洲 核子 研究 组 织 (CERN) 的 科学 家 Tim Berners-Lee 创建 了 一 个 叫 Web 
(World Wide Web, 万 维 网 ) 的 新 系统 ， 能 够 通过 Web 浏览 器 访问 因特网 上 链接 的 文档 。 
由 于 Web 文档 大 多 用 HTML 语言 书写 ,浏览 这 些 文档 需要 一 个 特殊 的 应 用 协议 : HTTP 
(HyperText Transfer Protocol， 超 文本 传输 协议 ) 。 这 种 协议 是 网 站 运行 和 Web API 工作 的 
核心 。 











本 章 ， 我 们 将 深入 了 解 Web 体系 结构 的 基本 知识 ， 探 究 HTTP 协议 。 这 将 为 我 们 下 一 步 设 
计 Web API 奠定 基础 。 


1.1 Web 体 系 结构 


如 图 1-2 Aras, Web 有 三 个 核心 概念 : 资源 (resource), URI (Uniform Resource Identifier, 
统一 资源 标识 符 ) 和 表示 (representation) ， 参 见 http:/www.w3.org/TR/webarch 。 





URI 


http://mycontacts.com/contacts/1 


“Contactld”: 1, 联系 人 处 理 代码 


“Name”: “Glenn Block’, 
“Address”: ”1 Microsoft Way”, 


} 








application/json 


媒体 类 型 











1-2: Web 核心 概念 


一 个 资源 由 一 个 URI 进行 标识 ， 而 HTTP 客户 端 使 用 URI 就 可 定位 资源 。 表 示 是 从 资源 





返回 的 那些 数据 。 和 Web 相关 的 另 一 个 重要 概念 是 媒体 类 型 (media type), ， 指 的 是 从 资源 
返回 数据 的 格式 。 

1.1.1 资源 

任何 带 有 URI 标识 的 东西 都 是 资源 。 资 源 自 身 是 一 个 或 多 个 实体 的 概念 性 映射 (http:/ 
tools.ietf.org/html/rfc2396#section-1.1)。 早 年 的 Web 中， 资源 映射 的 实体 通常 是 一 个 文件 ， 
如 一 份 文 档 或 者 一 个 网 页 。 不 过 ， 资 源 并 不 只 限于 文件 。 它 可 以 是 一 个 可 建立 连接 的 服 
务 ， 通 过 它 可 访问 产品 目录 、 连 接 设 备 (如 打印 机 ) 或 者 车 库 门 无 线 遥 控 器 ， 也 可 以 是 一 
个 像 CRM (Customer Relationship Management， 客 户 关 系 管理 ) 或 采购 系统 那样 的 内 部 系 
统 。 资 源 还 可 以 是 一 个 流 媒体 ， 如 视频 流 或 者 音频 流 。 


























资源 必须 关联 实体 或 者 数据 库 吗 ? 


现在 ， 人 们 对 于 Web API 有 一 个 常见 的 误解 ， 认 为 一 个 资源 必须 对 应 到 一 个 有 数据 库 
支持 的 实体 或 者 业务 对 象 。 在 讨论 设计 时 经 常会 有 人 说 :“ 我 们 不 能 用 这 个 资源 ， 因 为 
这 个 资源 需要 在 数据 库 中 创建 一 个 表 ， 而 我 们 又 不 需要 这 张 表 。” 前 面 给 出 的 资源 定义 
中 描述 了 到 一 个 或 多 个 实体 的 映射 这 里 所 说 的 实体 是 泛 指 的 (也 就 是 说 ， 实 体 可 以 
是 任何 东西 )， 而 不 是 特 指 业务 对 象 。 一 个 应 用 程序 可 以 这 样 设计 ， 让 其 中 提供 的 资源 
总 是 映射 到 业务 实体 或 数据 库 表 ， 对 这 种 系统 而 言 ， 前 面 那 种 说 法 确实 是 正确 的 。 但 
是 ， 这 种 限制 是 由 应 用 或 框架 强加 的 ，Web API 本 身 并 没有 这 种 限制 。 


在 构建 Web API 时 ， 这 种 实体 /资源 的 限制 在 很 多 情况 下 会 导致 问题 。 例 如 ， 一 个 订 
单 处 理 资源 ， 在 处 理 一 个 订单 时 实际 上 会 统筹 实施 不 同 的 系统 。 在 这 种 情况 下 ， 执 行 
这 个 资源 会 调用 系统 的 几 个 部 分 ， 这 些 部 分 会 各 自在 数据 库 中 存储 状态 ， 而 这 个 资源 
自身 可 能 在 数据 库 中 存储 状态 ， 也 可 能 不 存 。 问 题 的 关键 是 ， 这 个 资源 在 数据 库 中 没 
有 直接 对 应 关系 。 并 且 ， 被 调用 的 各 个 组 件 也 并 不 一 定 要 使 用 数据 库 (虽然 在 前 面 例 
子 中 是 使 用 了 数据 库 的 ) 。 


在 设计 Web API 时 ， 请 记 住 上 述 区 别 ， 这 可 以 帮助 你 在 系统 中 真正 发 挥 Web 的 力量 。 











1.1.2 URI 


如 前 所 述 ， 每 个 资源 都 可 以 通过 唯一 的 URI (http://tools.ietf.org/html/ric3986) 访问 。 你 
可 以 把 URI 看 成 一 个 资源 的 主键 (primary key), URI 的 例子 有 : http://fabrikam.com/ 
orders/100、http://ftp.fabrikam.com、mailto:John.Doe@example.com、 telnet://192.168.1.100 
以 及 urn:isbn:978-1-449-33771-1。 一 个 URI 只 能 对 应 一 个 资源 ， 但 是 多 个 URI 可 以 指向 同 
一 个 资源 。 每 个 URI 的 格式 都 是 : =scheme:hierarchical part[?query][#ragmentJ]， 其 中 查询 
字符 串 “query” 和 “fragment” 是 可 选 的 ， 这 里 的 “Hierarchical part” 还 可 以 包含 安全 证 
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书 颁发 机 构 (authority) 和 分 层 路 径 (hierarchical path) 。 


URI 分 为 两 种 类 型 : 统一 资源 定位 符 和 统一 资源 名 。URL (Universal Resource Locator, 
统一 资源 定位 符 ) 既 标识 一 个 资源 ， 又 指定 了 访问 该 资源 的 方法 ， 而 URN (Universal 
Resource Name， 统 一 资源 名 ) 仅仅 是 一 个 资源 的 唯一 标识 符 。 前 面 给 出 的 URI 例子 中 ， 
最 后 一 个 例子 是 本 书 的 URN， 其 他 都 是 URL。 这 个 URN 只 标识 了 本 书 ， 但 是 不 包含 关于 
如 何 获取 该 书 的 信息 。 在 实际 应 用 中 ， 你 看 到 的 大 多 数 URI 都 是 URL, AE URI 和 URL 
常常 同 义 替换 使 用 。 











是 否 使 用 查询 字符 串 ? 


有 一 个 经 常 被 讨论 的 问题 : 要 不 要 在 URI 中 使 用 查询 字符 囊 ? 这 个 问题 的 回答 和 缓存 
机 制 有 关 。 有 些 缓存 会 自动 忽略 任何 带 有 查询 字符 串 的 URI。 也 就 是 说 ， 所 有 带 查 询 
字符 串 的 URI 请求 都 会 转 到 源 服 务 器 (origin server) 进行 处 理 ， 而 这 会 对 系统 的 扩展 
产生 重要 影响 。 于 是 ， 有些 人 倾向 于 不 使 用 查询 字符 事 ， 而 把 这 部 分 信息 放 在 URI 路 
JEP, BRAG YA (参见 https://developers.google.com/speed/docs/insights/LeverageB 
rowserCaching#LeverageProxyCaching) Æ: 对 静态 资源 不 要 使 用 查询 字符 事 , 以 便 缓存 。 











1.1.3 酷 URI 


酷 URI (http://www.w3.org/TR/cooluris/#cooluris ) 是 简单 易 记 而 且 不 变 的 URI (例如 http:// 
www.example.com/people/alice), 408 URI 发 生 改 变 ， 那 么 链接 到 这 个 URI 的 现 有 系统 将 
不 能 继续 工作 ， 所 以 有 些 URI 需要 保持 不 变 。 如 果 你 希望 客户 端 保存 指向 你 的 资源 的 书 
签 ， 那 么 就 应 该 考虑 使 用 酷 URI。 如 果 你 有 一 些 网 页 ， 常 常 被 其 他 网 站 添加 链接 ， 或 者 被 
用 户 存储 在 浏览 器 收藏 夹 里 ， 那 么 ， 酷 URI 会 非常 好 用 。 但 是 ， 不 是 所 有 情况 下 都 要 用 到 
酷 URI。 你 在 这 本 书 中 将 会 看 到 ， 不 必用 很 多 酷 URI，API 设计 也 可 以 做 得 很 好 。 












































1.1.4 表示 

表示 是 资源 在 其 个 时 刻 状 态 的 快照 。 当 HTTP 客户 端 请 求 一 个 资源 时 ， 返 回 的 是 这 个 资源 
的 表示 ， 而 不 是 资源 本 身 。 从 一 个 请 求 到 下 一 个 请 求 发 生 时 ， 资 源 的 状态 可 能 会 发 生 很 大 
的 变化 ， 因 而 返回 的 表示 也 会 大 不 相同 。 例 如 ， 假 设 有 一 个 提供 开发 者 文章 的 API， 通 过 
访问 URI hitp://devarticles.com/articles/top 得 到 排名 第 一 的 文章 ， 这 个 API 返回 的 不 是 指 
向 该 URI 内 容 的 链接 ， 而 是 到 那 篇 文章 的 重 定向 信息 。 随 着 时 间 的 推移 ， 文 章 排名 发 生 
变化 ，( 重 定向 返回 的 ) 资源 的 表示 也 会 随 之 改变 。 在 这 个 例子 里 ， 资 源 并 不 是 那 篇 文章 ， 
而 是 服务 器 上 运行 的 逻辑 ， 这 个 逻辑 从 数据 库 中 获取 排名 第 一 的 文章 ， 从 而 返回 重 定向 信 
息 。 需 要 注意 的 是 ， 一 个 资源 可 以 有 一 个 或 多 个 表示 ， 详 见 1.2.84, 

















1.1.5 “媒体 类 型 


每 个 表示 都 有 特定 的 格式 ， 即 媒体 类 型 (media type)。 媒 体 类 型 是 在 因特网 上 客户 端 和 
服务 器 之 间 传 递 信息 的 格式 。 媒 体 类 型 由 两 部 分 标识 组 成 ， 例 如 text/html。 媒 体 类 型 有 
多 种 用 途 。 有 些 媒 体 类 型 非常 通用 ， 例 如 ，application/json (表示 一 组 值 或 一 组 键 值 ) 
或 text/html (主要 用 于 在 浏览 器 中 显示 文档 )。 另 一 些 媒 体 类 型 的 语法 限制 较 多 ， 例 如 ， 
application/atom+xml 和 application/collection+json， 专 门 用 于 管理 源 和 列表 。 还 有 用 
于 PNG 图 像 的 image/png 媒体 类 型 。 媒 体 类 型 也 可 以 是 专属 于 特定 领域 的 ， 例 如 text/ 
vcard 用 于 名 片 和 联络 信息 的 电子 化 共享 。 附 录 A 列 出 了 一 些 常 见 的 媒体 类 型 。 




















媒体 类 型 自身 实际 上 包含 两 部 分 。 第 一 部 分 ( 斜 线 前 ) 是 顶级 媒体 类 型 ， 这 部 分 描述 了 通 
用 的 类 型 信息 以 及 常用 处 理 规 则 。 常 见 的 顶级 类 型 有 : application, image, text, video 
和 multipart。 第 二 部 分 是 子 类 型 (subtype)， 描 述 一 个 非常 具体 的 数据 格式 。[ image/ 
png Fil image/gif 为 例 ， 它 们 的 顶级 类 型 告诉 客户 端 这 是 一 个 图 像 (image)， 而 子 类 型 png 
和 gif 具体 说 明了 这 是 什么 类 型 的 图 像 ， 应 该 如 何 处 理 。 子 类 型 经 常 有 不 同 的 变种 ， 使 用 
一 样 的 语法 ， 但 格式 不 同 。 例 如 ，HAL (Hypertext Application Language， 超 文本 应 用 程序 
语言 ，http://stateless.co/hal_specification.html) 有 两 个 变种 : JSON (application/hal+json) 
和 XML (application/hal+xml)。 子 类 型 hal+json 说 明 该 HAL 使 用 JSON 传输 格式 ， 而 
hal+xml 说 明 使 用 的 是 XML 传输 格式 。 























媒体 类 型 的 起 源 


媒体 类 型 最 早 源 自 ARPANET。 最 初 ， ARPANET 是 通过 简单 文本 信息 进行 通信 的 
计算 机 网 络 。 系 统 不 断 扩 展 ， 开 始 需要 更 为 多 样 的 通信 。 于 是 ， 标 准 格式 (http:/ 
tools.ietf.org/html/rfc822) 被 制定 出 来 ， 使 信息 可 以 和 包含 与 其 处 理 相关 的 元 数据 。 随 
着 时 间 的 推移 和 电子 邮件 的 产生 ， 这 个 标准 演变 为 MIME (Multipurpose Internet Mail 
Extension， 多 用 途 因 特 网 邮件 扩展 ，http://tools.ietf.org/html/rfc2045)。MIME 的 用 途 
之 一 是 支持 非 文 本 格式 内 容 ， 从 而 产生 了 媒体 类 型 (http://tools.ietf.org/html/rfc2046)， 
用 于 描述 一 个 MIME 实体 的 主体 。 随 着 因特网 的 莲 勃 发 展 ， 人 们 不 必 使 用 电子 邮件 
就 可 以 在 Web 上 传送 同样 丰富 的 信息 ， 因 此 媒体 类 型 也 开始 用 于 描述 HITP 请 求 和 
响应 的 主体 ， 从 而 与 Web API 联 系 在 了 一 起 。 











媒体 类 型 注册 

通常 媒体 类 型 是 注册 在 一 个 由 IANA (Internet Assigned Numbers Authority， 因 特 网 号 码 分 
配 局 ) 管理 的 中 央 注 册 库 (http:/www.iana.org/assignments/media-types/media-types.xhtml ) 
中 。 这 个 注册 库 本 身 包含 一 份 媒体 类 型 列表 ， 以 及 到 相关 说 明 书 的 链接 。 注 册 表 按照 顶级 
媒体 类 型 进行 分 类 ， 每 个 顶级 分 类 包含 一 份 具 体 媒 体 类 型 的 列表 。 














应 用 程序 开发 者 要 设计 能 够 识别 标准 媒体 类 型 的 客户 端 或 服务 器 ， 就 可 以 参考 这 个 媒体 
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类 型 注册 库 。 例 如 ， 如 果 你 要 创建 一 个 识别 image/png 媒体 类 型 的 客户 端 ， 可 以 导航 到 
IANA 媒体 类 型 页 面 (http:/www.iana.org/assignments/media-types/media-types.xhtml) 的 
image 分 类 ， 查 找 “png”， 得 到 image/png 类 型 的 说 明 ， 具 体 页 面 如 图 1-3 所 示 。 

















Image Media Types 


Internet Assigned Numbers Authority 


image 
Computer Graphics Metafile [Francis] 

RFC4735) 
[RFC4047 

RFC1494] 
[RFC2045,RFC2046) 
Image Exchange Format [RFC1314] 
[RFC3745 
RFC2045,RFC2046) 



































1-3: IANA 注册 库 的 image 分 类 


为 什么 要 有 这 些 不 同 的 媒体 类 型 呢 ? 因为 每 个 类 型 都 有 各 自 的 优点 ， 或 者 有 其 量 身 定做 的 
客户 端 。HTML 类 型 展示 文档 (例如: Web 页面) 效果 极 佳 ， 但 不 一 定 最 适合 于 传输 数 
据 。JSON 传输 数据 很 好 用 ， 但 是 在 重 现 图 像 上 效率 却 十 分 低下 。PNG 是 极 好 的 图 像 格 式 ， 
但 在 存储 可 扩展 的 矢量 图 形 方面 不 大 理想 ， 对 此 SVG 才 是 优选 。 比 起 不 成 熟 的 XML 或 
JSON, ATOM, HAL 和 Collection+JSON 能 表达 更 为 丰富 的 应 用 程序 语义 ， 不 过 ， 它 们 受 
到 的 限制 也 较 多 。 

















读 到 这 里 ， 你 已 经 了 解 了 Web 体系 结构 的 核心 组 件 。 下 一 方 我 们 将 详细 了 解 HTTP 一 一 将 
所 有 这 些 组 合 起 来 的 黏合 剂 。 


1.2 HTTP 协议 


介绍 完 大 体 的 Web 体系 结构 ， 我 们 接 下 来 看 HTTP。HTTP 协议 涵盖 广泛 ， 因 此 我 们 并 不 
试图 介绍 所 有 内 容 ， 而 是 关注 一 些 主要 概念 ， 特 别 是 那些 和 构建 Web API 相关 的 概念 。 如 
果 你 初 识 HITP， 这 部 分 内 容 应 该 正好 可 以 帮 你 打下 基础 ， 如 果 不 是 ， 你 也 应 该 能 习 得 原 
本 不 知道 的 知识 ， 不 过 跳 过 这 部 分 内 容 也 无 妨 。 


HTTP (http://www.w3.org/Protocols/rfc2616/rfc2616.html) 是 信息 系统 的 应 用 层 协 议 ， 是 
驱动 Web 的 核心 。HTTP 协议 原本 由 三 位 计算 机 科学 家 提出 ， 他 们 是 : Tim Berners-Lee, 
Roy Fielding 和 Henrik Frystyk Nielsen, HTTP 协议 定义 了 供 客户 端 和 服务 器 在 网 络 上 传输 
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信息 的 统一 接口 ， 让 它们 无 需 了 解 执 行 的 具体 细节 。HTTP 协议 是 为 支持 动态 变化 的 系统 
而 设计 的 ， 可 以 容忍 一 定 程度 的 延迟 和 陈旧 。 这 种 设计 允许 中 间 层 (例如: 代理 服务 器 ) 
介入 通信 ， 提 供 各 种 功能 ， 例 如 缓存 、 压 缩 以 及 路 由 选择 。 万 维 网 规模 庞大 ， 不 断 变化 ， 
而 网 络 拓扑 持续 展开 ， 延 迟 不 可 避免 ， 而 HTTP 协议 因 其 特性 ， 正 好 成 为 万 维 网 的 理想 协 
iM. A 1996 年 诞生 时 起 ，HTTP 协议 就 一 直 驱 动 着 万 维 网 的 运行 ， 经 受 住 了 时 间 的 考验 。 


















































1.2.1 HTTP 1.1 之 后 

HTTP 不 是 一 成 不 变 的 ， 我 们 理解 以 及 使 用 它 的 方式 都 在 进化 。 由 于 文本 的 模糊 性 ， 某 
些 时 候 甚至 被 认为 错误 ， 围 绕 HTTP 协议 规范 RFC 2616， 存 在 着 很 多 的 误解 。IETF 
(Internet Engineering Task Force， 互 联网 工程 任务 组 ) 成 立 了 一 个 名 为 httpbis (http:// 
datatracker.ietf.org/wg/httpbis/charter/) 的 工作 组 ， 这 个 工作 组 创建 了 一 套 草 案 (http:/ 
datatracker.ietf.org/wg/httpbis/documents/) ， 专 门 用 于 取代 RFC 2616， 潍 清 误 解 。 此 外 ， 这 
个 工作 组 还 承担 着 创建 HTTP 2.0 规范 (http://datatracker.ietf.org/doc/draft-ietf-httpbis-http2/) 
的 任务 。HTTP 2.0 不 会 影响 HTTP 协议 公开 的 表层 领域 ， 而 是 对 底层 传输 进行 了 一 组 优 
化 ， 例 如 采用 新 的 SPDY 协议 (http://tools.ietf.org/html/draft-mbelshe-httpbis-spdy-00). Al 
为 httpbis 的 存在 是 为 取代 HTTP 协议 规范 ， 并 且 ， 也 帮助 人 们 建立 对 HTTP 更 为 完善 的 理 
解 ， 我 们 将 使 用 httpbis 草案 作为 下 文 的 基础 。 


















































1.2.2 “HTTP 消息 交换 


基于 HTTP 协议 的 系统 以 一 种 无 状态 的 方式 ， 使 用 请 求 / 响应 模式 进行 信息 交换 。 我 们 将 
简单 介绍 这 一 交换 过 程 。 首 先 ， 一 个 HTTP 客户 端 后 成 一 个 HTTP 请 求 ， 如 图 1-4 所 示 。 




















方法 URI 版 本 


POST http://localhost:8081/api/contacts HTTP/1.1 
User-Agent: Fiddler 
Host: localhost:8081 
标 头 < Accept: application/json 
Content-Type: application/json 
Content-Length: 121 


{ 
“Name”: “Jane User:, 
“Address”: “1 Any Street’, 
实体 正文 “City”: “Any city’, 
(内 容 ) “State”: “WA’, 
“Zip”: “00000", 
“Email”: “janeuser@example.com” 


} 











1-4, HTTP 请 求 
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这 个 HTTP 请 求 是 一 个 消息 ， 其 中 包含 一 个 HTTP 版 本 、 一 个 所 访问 资源 的 URI、 请 求 标 
头 (header) 和 一 个 HTTP 方 法 (如 GET)， 还 可 以 包含 一 个 可 选 的 实体 正文 (内容)。 这 个 
请 求 随后 发 送 到 资源 所 在 的 源 服务 器 (origin server)。 服 务 器 查看 URI 和 HTTP Wik, LA 
判断 自己 是 否 能 够 处 理 这 个 消息 。 如 果 服 务 器 可 以 处 理 这 个 消息 ， 就 查看 请 求 标 头 中 包含 
的 控制 信息 〈 如 内 容 描 述 ) ， 然 后 基于 这 些 信息 处 理 消 息 。 

















服务 器 完成 消息 处 理 之 后 ， 就 生成 了 一 个 HTTP 响应 ， 通 常 包 含 所 请 求 资 源 的 一 个 表示 
(如 图 1-5 所 示 ) 。 




















版 本 状态 码 


HTTP/1.1 201 Created 

Cache-Control: no-cache 

Pragma: no-cache 

Content-Type: application/json; charset=utf-8 
Expires: -1 

Location: http://localhost:8081/api/contacts/6 
Server: Microsot-II5/8.0 

X-AspNet-Version: 4.0.30319 

X-Sourceiles: =?UTF-8?B? 
QzpcQ29udGFjdEThbmFnZXJcOyNcQ29udGFjdE1hb 
X-Powered-By: ASP.NET 

Date: Sat, 22 Dec 2012 21:31:04 GMT 
Content-Length: 175 


标 头 


“Name”: “Jane User:, 
“Address”: "1 Any Street’, 
实体 正文 “City”: “Any city”, 
(内 容 ) “State’:“WA’, 
“Zip":“00000", 


“Email”: “janeuser@example.com” 











1-5; HTTP 响应 





HTTP 响应 包含 HTTP 版 本 、 响 应 标 头 、 可 选 的 实体 主体 〈 其 中 包含 资源 表示 )、 一 个 状态 
码 和 一 个 描述 。 与 收 到 消息 的 服务 器 类 似 ， 客 户 端 会 检查 响应 标 头 ， 使 用 其 控制 信息 对 消 
息 及 其 内 容 进 行 处 理 。 
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前 述 的 HTTP 信息 交换 过 程 虽然 准确 ， 但 遗漏 了 一 个 重要 部 分 : 中 间 层 (http://tools.ietf. 
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org/html/draft-ietf-httpbis-pl-messaging-21#section-2.3)。HTTP 是 一 个 具有 层次 的 结构 ， 系 
统 中 的 每 个 组 件 /服务 器 都 有 各 自 不 同 的 关注 点 ，HTTP 客户 端 也 不 需要 “看 见 ” 源 服务 
器 。 在 HTTP 请 求 向 源 服务 器 传递 时 ， 它 会 遇 到 如 图 1-6 所 示 的 中 间 层 。 中 间 层 是 一 些 代 
理 或 组 件 ， 检 查 HTTP 请 求 或 响应 ， 可 能 对 其 进行 修改 或 者 禁 换 。 一 个 中 间 层 可 以 立即 返 
回 一 个 响应 ， 触 发 某 些 过 程 (如 记录 详细 日 志 )， 或 者 只 是 让 HTTP 请 求 通过 。 中 间 层 具 
有 一 些 优点 ， 可 以 增强 或 者 改进 通信 方式 。 例 如 ， 缓 存 可 以 通过 返回 来 自 源 服务 器 的 缓存 
结果 来 缩短 响应 时 间 。 


























图 1-6: HTTP 中 间 层 


请 注意 : 中 间 层 可 以 存在 于 HTTP 请 求 从 客户 端 到 源 服务 器 经 过 的 任何 地 方 ， 具 体 处 在 什 
么 位 置 并 不 重要 。 中 间 层 既 可 以 和 客户 端 或 源 服务 器 运行 在 同一 台 机 器 上 ， 也 可 以 是 因 特 
网 上 一 台 专 用 的 公共 服务 器 。 中 间 层 也 可 以 内 建 在 系统 内 ， 如 Windows 系统 上 的 浏览 器 组 
存 ， 也 可 以 是 中 间 件 插件 。ASP.NET Web API 支持 多 种 可 用 于 客户 端 或 服务 器 的 中 间 件 ， 
如 处 理 程序 (handler) 和 筛选 器 (filter), 38 4 章 和 第 10 章 将 对 此 进行 介绍 。 








1.2.4 ”中 间 层 类 型 


参与 HTTP 消息 交换 并 对 客户 端 可 见 的 中 间 层 有 三 种 。 


。 代理 (proxy)， 它 代表 客户 端 发 出 HTTP 请 求 并 接受 响应 。 客 户 端 使 用 代理 时 采用 主动 
模式 ， 需 要 进行 相应 的 配置 。 很 多 组 织 都 会 使 用 内 部 代理 ， 组 织 内 的 用 户 必须 通过 这 个 
代理 访问 因特网 ， 这 种 做 法 非常 普遍 。 如 果 一 个 代理 有 意 对 HTTP 请 求 或 者 响应 进行 修 
改 ， 那 么 这 个 代理 就 是 转化 代理 (transforming proxy)。 不 修改 消息 的 代理 称 为 非 转化 
代理 (non-transforming proxy) 。 
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AX (gateway) 接受 传人 的 HTTP 消息 ， 将 其 翻译 为 服务 器 底层 的 协议 ， 底 层 协议 可 
能 是 HITP， 也 可 能 不 是 HTTP。 网 关 也 处 理 传 出 的 消息 ， 将 其 转化 为 HTTP 协议 。 网 
关 可 以 代表 源 服务 器 处 理 请 求 。 

隧道 (tunnel) 在 两 个 连接 之 间 建 立 一 个 私有 通道 ， 不 会 修改 任何 消息 。 隧 道 的 一 个 例 
子 是 两 个 客户 端 穿 过 防火 墙 用 HTTPS 进行 通信 。 

































































CDN 是 中 间 层 吗 ? 


另 一 种 常见 的 因特网 缓存 机 制 是 CDN (Content Delivery Network， 内 容 分 发 网 络 )。 
CDN 是 一 组 分 散 的 机 器 ， 缓 存 和 返回 静态 内 容 。 市 场 上 有 很 多 流行 的 CDN 服务 商 ， 
如 Akamai (http:/www.akamai.com/) ， 为 公司 提供 内 容 缓 存 。 那 么 ，CDN 是 中 间 层 
吗 ? 答案 取决 于 内 容 请 求 是 怎样 传递 给 CDN 1, WRAP HATE CDN 发 出 请 求 ， 
ARZ CDN 扮演 的 是 源 服 务 器 的 角色 。 有 些 CDN 功能 类 似 于 网 关 ， 对 客户 闹 是 不 可 见 
的 ， 但 和 它 实 际 上 代表 源 服 务 器 进行 操作 ， 缓 存 并 返回 所 请 求 的 内 容 。 








1.2.5 ”HTTP 方法 

HTTP 协议 提供 一 组 标准 方法 (参见 http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics- 
21#section-5.3)， 作 为 资源 访问 的 接口 。 在 最 早 的 HTTP 规范 发 布 后 ，PATCH 方法 (参见 
http://tools.ietf.org/html/rfc5789) 也 被 批准 通过 。 如 图 1-4 所 示 ，HTTP 方法 是 HTTP 请 求 
的 一 部 分 。 下 面 介 绍 API 开发 者 执行 的 常用 方法 。 








GET 
从 资源 获取 信息 。 如 果 返 回 资源 ， 服 务 器 应 该 返回 状态 码 200 (0K), 























HEAD 
与 GET 相同 ， 但 返回 标 头 而 非 主体 。 





POST 

请 求 服务 器 接受 消息 中 包含 的 实体 ， 交 由 目标 资源 处 理 。 作 为 请 求 处 理 过 程 的 一 部 分 ， 
服务 器 可 以 创建 一 个 新 的 资源 ， 但 不 一 定 如 此 。 如 果 服 务 器 创建 了 资源 ， 那 么 应 该 返回 
状态 码 201 (Created) 或 者 202 (Accepted) ， 并 返回 一 个 地 址 标 头 ， 告 知客 户 端 从 何 处 
访问 新 资源 。 如 果 服 务 器 没有 创建 资源 ， 那 么 应 该 返回 状态 码 200 (OK) 或 者 204 (No 
Content)。 在 实际 应 用 中 ，P05T 方法 基本 上 可 以 进行 任何 类 型 的 处 理 ， 不 受 任何 限制 。 





























PUT 

请 求 服务 器 将 指定 URI 所 代表 的 目标 资源 替换 为 消息 中 包含 的 实体 。 如 果 当 前 表示 对 
应 的 资源 存在 ， 服 务 器 应 该 返回 状态 码 200 (OK) 或 者 204 (No Content)。 如 果 对 应 的 
资源 不 存在 ， 那 么 服务 器 可 以 创建 这 个 资源 。 如 果 服 务 器 创建 了 资源 ， 应 该 返回 状态 码 
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201 (Created), POST 和 PUT 的 主要 区 别 在 于 : POST 方法 预期 数据 被 传人 人 加工， 而 PUT 
方法 预期 数据 被 替换 或 者 存储 。 


DELETE 

请 求 服务 器 移 除 指定 URI 所 代表 的 实体 。 如 果 服 务 器 立即 移 除 了 指定 的 资源 ， 那 
么 应 该 返回 状态 码 200 (OK)。 如 果 资 源 尚 未 移 除 ， 那 么 服务 器 应 该 返回 状态 码 202 
(Accepted) 或 者 204 (No Conent), 








OPTIONS 

请 求 服务 器 返回 功能 信息 。 大 多 数 情况 下 ， 服 务 器 返回 一 个 Allow 标 头 ， 有 具体 说 明 支 持 
哪些 HTTP 方法 ， 尽 管 协 议 规 范 对 此 并 没有 硬性 规定 。 例 如 : 服务 器 完全 可 以 列 出 支持 
哪些 媒体 类 型 。0PTIONS 方法 也 可 以 返回 一 个 正文 ， 提 供 在 标 头 内 无 法 表示 的 更 多 信息 。 

















PATCH 

请 求 服务 器 对 指定 URI 所 代表 的 实体 进行 部 分 更 新 。PATCH 方法 中 应 该 包含 足够 的 信 
息 ， 供 服务 器 进行 所 请 求 的 更 新 。 如 果 指 定 的 资源 存在 ， 服 务 器 可 以 进行 更 新 并 返回 
状态 码 200 (OK) 或 者 204 (No Content)。 与 PUT 的 处 理 方法 类 似 ， 如 果 指 定 的 资源 
不 存在 ， 服 务 器 可 以 创建 这 个 资源 。 如 果 服 务 器 创建 了 资源 ， 就 应 该 返回 状态 码 201 
(Created) 。 如 果 一 个 资源 支持 PATCH 方法 ， 那 么 OPTIONS 响应 的 ALLow 标 头 可 以 对 此 进 
行 说 明 。 服 务 器 也 可 以 使 用 Accept-Patch 标 头 ， 列 出 客户 端 可 以 对 其 发 送 PATCH 请 求 
的 媒体 类 型 。 协 议 规范 建议 媒体 类 型 应 包含 语义 ， 向 服务 器 传递 部 分 更 新 所 需 的 信息 。 
json-patch (参见 https://tools.ietf.org/html/draft-pbryan-json-patch-04) 是 一 个 提议 的 媒 
体 类 型 草案 ， 支 持 表 达 部 分 更 新 中 所 需 的 操作 。 



























































TRACE 

请 求 服务 器 返回 其 收 到 的 请 求 。 服 务 器 返回 一 个 content-type 4 message/http 的 正文 ， 
其 中 包含 完整 的 请 求 信息 。 客 户 端 可 以 使 用 TRACE 方法 ， 查 看 请 求 消息 经 过 的 代理 以 及 
中 间 层 对 消息 所 做 的 修改 ， 有 助 于 进行 问题 诊断 。 








1. 条 件 请 求 

HTTP 协议 的 一 个 额外 特征 是 可 以 让 客户 端 发 出 附 条 件 的 请 求 。 要 进行 这 种 请 求 ， 客 户 
端 需 要 发 送 特殊 的 标 头 ， 为 服务 器 处 理 请 求 提供 所 需 的 信息 。 这 种 特殊 的 标 头 包括 If- 
Match, If-NoneMatch 和 If-ModifiedSince, Pat B 中 的 表 B-2 将 详细 描述 这 些 标 头 。 


条 件 GET ”服务 器 可 以 通过 客户 端 发 送 的 标 头 ， 判 断 客户 端 缓存 的 资源 表示 是 否 仍然 有 
效 。 如 果 客 户 端的 缓存 仍然 有 效 ， 那 么 服务 器 不 返回 所 请 求 资源 的 表示 ， 而 是 返回 状态 
码 304 (Not Modified)。 使 用 条 件 GET 可 以 减少 网 络 流量 (因为 响应 消息 很 短 ), 还 可 以 
降低 服务 器 的 负载 。 
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。 条 件 PUT 服务 器 可 以 通过 客户 端 发 送 的 标 头 ， 判 断 客户 端 缓存 的 资源 表示 是 否 仍然 有 
效 。 如 果 客 户 端 缓存 仍然 有 效 ， 服 务 器 返回 状态 码 409 (Preconditions Failed)。 条 件 
PUT 可 以 用 于 并 发 处 理 。 使 用 条 件 PUT， 客 户 端 可 以 判断 在 自己 发 起 请 求 时 是 否 有 另 一 
个 用 户 修改 了 数据 。 


2. 方法 属性 
HTTP 方法 可 以 具有 如 下 的 附加 属性 。 








。 安全 (safe) 使 用 安全 的 HTTP 方法 发 送 请 求 ， 从 用 户 方面 不 会 产生 任何 副作用 。 这 
并 不 是 说 安全 方法 根本 不 会 产生 副作用 ,而 是 说 用 户 可 以 使 用 这 个 方法 安全 地 发 起 请 求 ， 
不 用 担心 无 意 间 修改 了 系统 状态 。 

。 3 = (idempotent) 通过 竹 等 方法 对 资源 发 出 一 次 请 求 ， 与 多 次 请 求 效果 相同 。 按 照 
定义 ， 所 有 的 安全 方法 都 是 备 等 的 。 有 些 方法 不 是 安全 的 ， 但 也 可 以 是 适 等 的 。 与 安全 
方法 类 似 ， 使 用 短 等 方法 的 请 求 并 不 能 保证 在 服务 器 端 不 产生 任何 副作用 ， 但 是 这 些 可 
能 的 副作用 和 用 户 无 关 。 

。 可 缓存 (cachable) 可 缓存 方法 可 以 从 中 间 层 缓存 处 ， 获 取 对 之 前 请 求 缓存 的 响应 。 


K 1-1 列 出 了 HTTP 方法 及 其 是 否 为 安全 、 略 等 或 可 缓存 方法 。 


表 1-1: HTTP 方 法 
全 











Fi ik 
GET 





HEAD 
POST 
PUT 
DELETE 
OPTIONS 
PATCH 
TRACE 


i ON a OY ON D Am a] 
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在 以 上 列 出 的 方法 中 ， 如 今 的 API 开发 者 最 常 使 用 的 是 GET, PUT, POST, DELETE 和 HEAD, 
PATCH 是 个 新 方法 ， 但 在 逐渐 得 到 普遍 地 使 用 。 


设置 一 套 HTTP 标准 方法 具有 如 下 优势 。 





。 只 要 HTTP 资源 遵循 协议 规范 ， 任 何 HTTP 客户 端 都 可 以 与 其 交互 。 客 户 端 可 以 使 用 方 
法 ， 如 OPTIONS 获取 和 发 现 信息 ， 从 而 了 解 如 何 交 互 。 

。 服务 器 可 以 进行 优化 。 代 理 服务 器 和 Web 服务 器 可 以 选择 一 些 方法 提供 优化 。 例 如 : 
缓存 代理 知道 GET 请 求 可 以 缓存 ， 因 此 ， 如 果 你 发 出 一 个 GET 请 求 ， 代 理 就 可 以 返 
个 缓存 的 资源 表示 ， 不 需要 把 请 求 发 送 给 服务 器 。 











ÉE 
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1.2.6 标 头 
HTTP 消息 的 标 头 (header) 字段 为 客户 端 和 服务 器 提供 信息 ， 用 于 处 理 这 个 HTTP 请 求 。 
标 头 有 四 种 类 型 ; 消息、 请 求 、 响 应 和 表示 。 


请 求 和 响应 信息 都 可 以 包含 消息 标 头 。 消 息 标 头 提 供 的 信息 与 消息 自身 而 非 实体 正文 相 
关 ， 有 具体 包括 : 


。 与 中 间 层 相关 的 标 头 ， 如 Cache-Control, Pragma 和 Via; 
。 与 消息 相关 的 标 头 ， 如 Transfer-Encoding 和 Trailer; 
。 与 请 求 相 关 的 标 头 ， 如 Connection, Upgrade 和 Date, 


。 ARRA 
请 求 消息 通常 可 以 包含 请 求 标 头 ， 实 体 正文 则 不 包含 请 求 标 头 ,但 Range 标 头 除外 。 请 
求 标 头 包括 ， 





。 关于 请 求 的 标 头 ， 如 Host、Expect 和 Range; 

。 用 于 身份 验证 信息 的 标 头 ， 如 User-Agent 和 Form; 

。 用 于 内 容 协商 的 标 头 ， 如 Accept、Accept-Language 和 Accept-Encoding; 

© 用 于 条 件 请 求 的 标 头 ， 如 If-Match、If-None-Match 和 If-Modified-Since, 


。 响应 标 头 
响应 消息 可 以 包含 响应 标 头 ， 实 体 正文 不 包含 响应 标 头 。 响 应 标 头 包括 : 











。 提供 目标 资源 信息 的 标 头 ， 如 Allow 和 Server; 

。 提供 附加 控制 数据 的 标 头 ， 如 Age 和 Location, 

。 与 所 选 表示 相关 的 标 头 ， 如 ETag, Last-Modified 和 Vary; 

。 与 认证 挑战 相关 的 标 头 ， 如 Proxy-Authenticate 和 WWW-Authenticate, 





请 求 或 响应 实体 主体 (内容) 通常 可 以 包含 表示 标 头 ， 包 括 : 





。 关于 实体 正文 自身 的 标 头 ， 如 Content-Type、Content-Length、Content-Location 和 


Content-Encoding; 
。 关于 实体 正文 缓存 的 标 头 ， 如 Expires。 
附录 B 提供 了 HTTP 规范 中 标准 标 头 的 完整 列表 和 描述 信息 。 


HTTP 规范 仍然 在 扩展 中 。 像 IETF (Internet Engineering Task Force， 因 特 网 工程 任务 组 ) 
或 W3C (World Wide Web Consortium, 万 维 网 联盟 ) 这 样 的 组 织 ， 可 以 提议 和 批准 新 的 
标 头 ， 扩 展 HTTP 协议 。HTTP 协议 扩展 的 两 个 例子 是 : 引入 新 的 缓存 标 头 的 RFC 5861 
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(http://tools.ietf.org/html/rfe5861) 和 引入 跨 源 访 标 头 的 CORS 规范 (http://www.w3.org/ 





TR/cors/)。 本 书后 面 章 节 会 对 这 两 个 扩展 进行 介 














1.2.7 HTTP 状态 码 


站 说 明 请 求 是 否 成 功 。 这 两 部 分 信息 由 源 服务 器 负责 返 




















， 告 知客 户 端 服 务 器 是 否 接受 或 成 功 处 理 了 请 求 ， 并 给 出 下 一 
ee peel 对 状态 码 进行 解释 。 状 态 码 的 范围 是 
态 码 的 不 同类 别 ， 以 及 相关 的 httpbis 参考 文档 。 





表 1-2: HTTP 状 态 码 


步 可 行 操作 的 建议 。 描 述 
4xx~5xx。 表 1-2 列 出 了 状 





范围 H 述 参考 文档 
ixx ” 收 到 请 求 ， 正 在 处 理 http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-21#section-7.2 





2xx ” 收 到 、 接 受 并 理解 了 请 求 ” http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-21#section-7.3 


3xx ”需要 更 多 操作 以 完成 请 求 ” http://tools.ietf.org/html/draft-ietf-httpbi 
4xx ”请 求 无 效 ， 无 法 完成 http://tools.ietf.org/html/draft-ietf-httpbi 
5xx ”服务 器 无 法 完成 请 求 http://tools.ietf.org/html/draft-ietf-httpbi 

















is-p2-semantics-21#section-7.4 
is-p2-semantics-21#section-7.5 


is-p2-semantics-21#section-7.6 


状态 码 可 能 与 其 他 标 头 直接 相关 。 在 下 面 展 示 的 响应 消息 片段 中 ， 服 务 器 返回 状态 码 201, 














表示 创建 了 新 资源 。Location 标 头 向 客户 端 指明 了 新 建 资源 的 
在 得 到 状态 码 201 时 应 该 自动 检查 Location 信息 。 





HTTP/1.1 201 Created 

Cache-ControL: no-cache 

Pragma: no-cache 

Content-Type: application/json; charset=utf-8 
Location: http://localhost:8081/api/contacts/6 


128 内 容 协 商 





URI， 这 样 ，HTTP 客户 端 


HTTP 服务 器 经 常 支持 同一 资产 的 多 种 表示 方式 。 资 源 的 表示 可 能 受到 多 种 因素 的 影响 ， 





如 客户 端的 不 同 功能 ， 或 基于 有 效 载 荷 的 优化 。 例 如 : PBA 
资源 会 返回 定制 的 vCard 表示 。HTTP 允许 客户 端 告知 服务 








程序 客户 端 ， 一 个 Contact 


器 其 偏好 ， 参 与 媒体 类 型 的 选 


择 。 客 户 端 和 服务 器 之 间 的 这 种 选择 过 程 称 为 内 容 协 商 (content negotiation， 参 见 http:// 
tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-21#section-3.4) 或 conneg。 





1.2.9 缓存 


正如 我 们 在 “方法 属性 ”部 分 提 到 的 ， 有 些 响应 是 可 缓存 的 ， 即 GET 和 HEAD 请 求 的 响应 。 
缓存 的 主要 好 处 是 可 以 提高 因特网 的 整体 性 能 和 规模 。 缓 存 可 以 通过 以 下 方式 为 客户 端 和 











源 服务 器 提供 帮助 : 
16 | 第 1 章 


。 由 于 客户 端 和 服务 器 之 间 的 往复 通信 数量 减少 ， 响 应 有 效 载 荷 也 得 以 降低 ， 客 户 端 因此 


xh jh 
Ss 


X m. 5 


。 中 间 层 可 以 返回 缓存 的 资源 表示 ， 减 少 了 源 服务 器 的 人 负载， 服务器 因此 受益 。 








HTTP 缓 寿 是 一 种 存储 机 制 ， 对 来 自 源 服务 器 的 缓存 响应 进行 增加 、 获 取 和 删除 等 管理 。 
缓存 只 尝试 处 理 那些 使 用 可 缓存 方法 的 请 求 ， 所 有 其 他 的 请 求 〈 使 用 不 可 缓存 的 方法 ) 都 
会 自动 转发 给 源 服务 器 。 如 果 请 求 是 可 缓存 的 ， 但 其 响应 在 缓存 中 不 存在 或 已 过 期 ,缓存 
也 会 把 请 求 转发 给 源 服务 器 。 


























httpbis 定义 了 一 个 相当 复杂 的 缓存 机 制 (参见 http://tools.ietf.org/html/draft-ietf-httpbis-p6- 
cache-21#section-4.1)。HTTP 缓存 机 制 有 很 多 更 完善 的 细节 ， 但 基本 上 是 建立 于 两 个 概念 : 
过 期 和 验证 。 


1. 过 期 

一 个 响应 中 ， 通 过 CacheControl 标 头 的 max-age 指定 了 一 个 时 间 最 大 值 ， 如 果 它 在 缓存 中 
存在 的 时 间 超 过 这 个 最 大 值 ， 那 么 这 个 响应 就 过 期 了 ， 或 者 说 “陈旧 ”(stale) 了 。 一 个 
响应 的 Expires 标 头 定义 了 一 个 过 期 时 间 ， 如 果 缓 存 服务 器 上 的 当前 时 间 超 过 了 这 个 过 期 
时 间 ， 那 么 这 个 啊 应 也 会 过 期 。 如 果 一 个 啊 应 没有 过 期 ， 那 么 缓存 就 可 以 用 它 满足 请 求 。 
不 过 ， 在 请 求 和 已 缓存 的 响应 中 ， 还 存在 其 他 一 些 控 制 数 据 (参见 下 面 的 “缓存 和 协商 响 
应 ”) 可 能 使 已 缓存 的 响应 不 能 使 用 。 


























2. 验证 

如 有 果 一 个 啊 应 过 期 ， 那 么 缓存 必须 重新 对 其 进行 验证 。 要 验证 一 个 响应 ， 缓 存 会 向 服务 喜 
发 送 一 个 条 件 GET 请 求 〈 参 见 “ 条 件 请 求 ") ， 询 问 已 缓存 的 响应 是 否 依然 有 效 。 所 发 送 的 
条 件 请 求 包 含 一 个 缓存 验证 码 ， 例 如 : 一 个 If-Modified-Since pA, (eM PAY Last- 
Modified 值 ， 或 者 一 个 If-None-Match 标 头 ， 包 含 响应 的 ETag 值 。 如 果 源 服务 器 认为 这 个 
响应 仍然 有 效 ， 就 会 返回 一 个 不 包含 主体 的 响应 ， 状 态 码 为 394 Not Modified， 以 及 一 个 
更 新 后 的 过 期 时 间 。 如 果 这 个 响应 已 经 改变 了 ， 那 么 源 服务 器 会 返回 一 个 新 的 响应 ， 而 这 
个 响应 会 被 最 后 保存 在 缓存 中 ， 取 代 当 前 缓存 的 资源 表示 。 





使 用 陈旧 的 响应 


在 某 些 特 定 的 情况 下 ， 比 如 源 服务 器 不 可 用 时 ，HTTP 会 允许 缓存 使 用 陈旧 的 响应 。 
在 这 种 情况 下 ， 绥 存 可 以 返回 陈旧 的 响应 ， 并 在 响应 中 包含 一 个 Warning 标 头 ， 以 告 
知 用 户 。Mark Nottingham 提出 的 “HTTP Cache-Control Extension for Stale Content” # 
案 (A R http://tools.ietf.org/html/rfc5861) ， 建 议 使 用 一 个 新 的 Cache-Control 指令 (A 
见 “ 缓 存 行 为 ") ， 以 解决 这 些 问 题 。 


在 验证 响应 的 过 程 中 ， 客 户 端 可 以 使 用 stale-while-revalidate 指令 ， 让 缓存 返回 陈旧 
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的 内 容 ， 以 避免 验证 的 延迟 。 如 果 网 络 出 现 故 障 或 者 源 服务 器 不 可 用 ,客户 端 可 以 使 
用 stale-if-error 指令 让 缓存 提供 内 容 。 这 两 个 指令 命令 缓存 : 如 果 请 求 包含 这 些 标 
头 ， 那 么 可 以 提供 陈旧 的 信息 。 之 前 提 到 的 Warning HAM RASS P HH, BAP 
的 内 容 确实 是 陈旧 的 。 


注意 : RFC 5861 被 标识 为 informational， 也 就 是 说 尚未 标准 化 ， 因 此 并 非 所 有 缓存 都 
会 对 这 些 附加 指令 提供 支持 。 











3. 无 效 

一 个 响应 在 缓存 后 ， 也 可 能 被 设置 为 无 效 。 一 般 情 况 下 ， 如 果 缓 存 观察 到 一 个 对 已 缓存 资 
源 的 请 求 使 用 了 非 安全 方法 ， 就 会 将 已 缓存 的 该 资源 响应 设置 为 无 效 。 如 果 请 求 的 方法 是 
修改 一 个 资源 的 状态 ， 那 么 缓存 就 知道 已 缓存 的 资源 表示 是 无 效 的 。 另 外 ， 如 果 观 察 到 
的 这 个 非 安全 请 求 的 响应 没有 错误 ， 那 么 缓存 也 应 该 将 这 个 请 求 的 Location 和 Content- 
Location 响应 设置 为 无 效 。 


4. 实体 标签 

实体 标签 或 称 ETag (参见 http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-2 1#section- 
2.3) , 是 当前 选 定 的 资源 表示 在 某 一 个 时 刻 的 验证 码 。 实 体 标 签 是 一 个 引用 的 “不 透明 ”的 
标识 符 ， 不 应 由 客户 端 解 析 。 服 务 器 可 以 在 响应 中 使 用 ETag 标 头 返回 实体 标签 (实体 标签 
也 可 以 缓存 ) 。 客 户 端 可 以 保存 实体 标签 ， 在 未 来 的 条 件 请 求 中 用 做 验证 码 ， 把 实体 标签 
作为 If-Match 或 If-None-Match 标 头 的 值 传递 给 服务 器 。 请 注意 : 这 里 提 到 的 客户 端 也 可 
以 是 中 间 层 缓存 。 服 务 器 收 到 请 求 后 ， 将 请 求 中 的 实体 标签 与 服务 器 上 的 受 请 求 资源 的 实 
体 标签 进行 比较 。 如 果 所 请 求 资 源 在 实体 标签 生成 后 发 生 了 变化 ， 那 么 服务 器 上 资源 的 实 
体 标 签 也 会 改变 ， 与 请 求 中 的 实体 标签 就 不 会 吻合 了 。 





























实体 标签 分 为 如 下 两 种 (参见 http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-21#section- 
2.1). 


。 强 实体 标签 (strong ETag) ” 当 服 务 器 的 资源 表示 改变 时 ， 强 实体 标签 也 会 随 之 改变 。 
一 个 资源 强 实体 标签 是 唯一 的 ， 与 同一 资源 的 其 他 所 有 表示 都 不 相同 (如 123456789)。 

。 弱 实 体 标签 (weak ETag) 弱 实 体 标签 不 一 定 随 着 资源 状态 进行 更 新 。 一 个 资源 的 弱 
实体 标签 也 不 必 限 定 为 唯一 ， 不 必 和 同 一 资源 的 其 他 表示 不 同 。 弱 实体 标签 必须 以 W/ 
开头 (如 W/123456789)。 














实体 标签 默认 是 强 实体 标签 ， 条件 请 求 应 优先 使 用 强 实体 标签 。 


5. 缓存 和 协商 响应 
通过 使 用 Vary 标 头 (参见 http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache-21#section-4.3)， 
缓存 可 以 提供 协商 的 响应 。 源 服务 器 可 以 使 用 Vary 标 头 指定 一 个 或 多 个 标 头 字段 ， 作 为 执 
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行内 容 协商 的 一 部 分 。 如 果 缓 存 中 的 一 个 资源 表示 带 有 Vary 标 头 ， 收 到 对 这 个 资源 的 请 求 
It, Vary 标 头 中 所 有 的 字段 都 必须 与 请 求 中 的 字段 相符 ， 才 有 资格 使 用 这 个 资源 表示 。 


下 面 例子 中 的 响应 使 用 了 Vary 标 头 ， 指 定 使 用 Accept 标 头 : 








7 











HTTP/1.1 200 OK 

Content-Type: application/json; charset=utf-8 
Content-Length: 183 

Vary: Accept 


6. 缓存 行为 

请 求 或 响应 通过 Cache-ControlL 标 头 (参见 http://tools.ietf.org/html/draft-ietf-httpbis-p6- 
cache-21#section-7.21) ， 向 缓存 机 制 说 明 自 己 的 缓存 特性 。 缓 存 行为 可 以 由 源 服务 器 在 响应 
中 提供 ， 也 可 以 由 客户 端 在 请 求 中 提供 。Cache-Control 标 头 的 值 是 一 列 缓存 指令 ， 说 明 
内 容 是 否 可 缓存 、 可 以 在 何 处 存储 、 过 期 策略 ， 以 及 什么 时 候 应 该 重新 验证 或 从 源 服 务 器 
重新 加 载 。 例 如 : no-cache 指令 要 求 缓存 每 次 在 提供 已 缓存 的 响应 前 都 必须 重新 验证 。 











Pragma 标 头 (参见 http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache-21#section-7.4) 也 可 以 
指定 no-cache 值 ， 与 Cache-Control 标 头 的 no-cache 指令 效果 相同 。 


下 面 给 出 的 响应 示例 使 用 了 Cache-Control 标 头 。 在 这 个 示例 中 ，Cache-Controlt 标 头 指定 
了 缓存 有 效 期 为 从 Last-Modified 时 间 之 后 3600 秒 〈 即 1 小 时 )， 还 指定 了 在 已 缓存 的 表 
示 过 期 后 ， 缓 存 服务 器 必须 向 源 服务 器 重新 验证 ， 然 后 才能 提供 内 容 。 





HTTP/1.1 200 OK 

Cache-Control: must-revalidate, max-age=3600 
Content-Type: application/json; charset=utf-8 
Last-Modified: Wed, 26 Dec 2012 22:05:15 GMT 
Date: Thu, 27 Dec 2012 01:05:15 GMT 
Content-Length: 183 

















附录 D 详细 介绍 了 缓存 的 行为 机 制 。 如 果 你 想 大 致 了 解 HTTP 缓存 ， 请 阅读 Ryan Tomayko 
的 “Things Caches Do” (http://tomayko.com/writings/things-caches-do) 和 Mark Nottingham 的 
“How Web Caches Work” (https://www.mnot.net/cache_docs/#WORK) 。 


1.2.10 ”身份 验证 

HTTP 为 服务 器 提供 一 个 可 扩展 框架 ， 帮 助 其 保护 资源 ， 并 让 客户 端 通过 身份 验证 机 制 
访问 服务 器 。 服 务 器 可 以 保护 一 个 或 多 个 资源 ， 每 个 资源 都 分 配 到 一 个 逻辑 分 区 ， 即 域 
(realm)。 每 个 域 都 有 各 自 的 身份 验证 方案 (authentication scheme) ， 或 者 支持 的 授权 方式 。 


服务 器 在 收 到 访问 受 保护 资源 的 请 求 时 ， 会 返回 一 个 状态 为 491 Unauthorized 或 403 
Forbidden 的 响应 ， 这 个 响应 还 包含 一 个 带 有 质询 (challenge) 的 WWW-Authenticate 标 头 ， 
说 明 客 户 端 必 须要 经 过 身份 验证 才能 访问 所 请 求 的 资源 。 质 询 是 一 个 可 扩展 令 牌 ， 描 述 身 
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ibaa 




















份 验证 方案 和 附加 的 认证 参数 。 例 如 : 如 果 要 访问 一 个 受 保护 的 联系 人 资源 ， 用 于 说 明 使 
用 HTTP 基本 认证 方案 的 质询 就 应 该 是 : Basic realm="contact" 





附录 也 详细 介绍 了 质询 — 响应 机 制 的 工作 机 制 。 


1.2.11 身份 验证 方案 


前 一 节 提 到 了 身份 验证 框架 ，RFC 2617 (参见 http://www.ietf.org/rfc/rfc2617.txt) 定义 了 两 
种 具体 的 身份 验证 机 制 : 


。 基本 认证 

在 基本 认证 方案 中 ， 用 户 名 和 密码 使 用 Base64 编码 ， 以 冒号 间隔 ， 通 过 明文 发 送 
用 户 身 份 凭据 。 因 为 其 自身 的 不 安全 性 ， 基 本 认证 (参见 http://tools.ietf.org/html/ 
rfc2617#section-2) 通常 和 TLS (Transport Layer Security， 传 输 层 安全 协议 ) 结合 在 一 
起 使 用 ， 即 为 超 文本 传输 安全 协议 (HTTPS)。 基 本 认证 非常 容易 实现 和 访问 (包括 从 
浏览 器 客户 端 进行 访问 )， 这 一 优点 使 得 很 多 API 开发 者 选择 使 用 基本 认证 。 


























。 摘要 认证 
使 用 摘要 认证 (参见 http://tools.ietf.org/html/rfc2617#section-3) 上 时， 用 户 的 身份 凭据 通过 明 
文 发 送 。 摘 要 认证 使 用 客户 端 发 送 的 一 个 校 验 和 (MAC, Message Authentication Code, iff 
息 校 验 码 )， 供 服务 器 验证 用 户 凭据 。 但 是 ， 摘 要 认证 有 一 些 安全 和 性 能 缺陷 ， 不 常 使 用 。 








看 的 示例 是 试图 访问 受 保护 资源 后 得 到 一 个 HTTP 基本 认证 的 质询 响应 。 


=| 














HTTP/1.1 401 Unauthorized 


WWW-Authenticate: Basic realm="Web API Book" 


如 你 所 见 ， 服 务 器 返回 了 一 个 401 状态 码 ， 响 应 中 包含 一 个 WWW-Authenticate 标 头 ， 说 明 
客户 端 必须 使 用 HTTP 基本 认证 方案 进行 认证 : 





GET /resource HTTP/1.1 


Authorization: Basic QNxpY2U6VahLIE1hZ2LjIFdvcmRzIGFyZSBTCXVLYWN1pc2ggT3NzaNZyYWdL 


之 后 ， 客 户 端 返回 原来 的 请 求 ， 并 加 入 Authorization 标 头 ， 以 访问 受 保护 的 资源 。 


1.2.12 ”附加 身份 验证 方案 


在 RFC 2617 制定 之 后 ， 又 出 现 了 一 些 新 的 身份 验证 方案 ， 包 括 一 些 厂商 相关 的 机 制 。 





e AWS 认 证 
这 种 方案 用 于 Amazon Web 服务 S3 (http://amzn.to/rest-services) 身份 验证 。 客 户 端 把 
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请 求 的 几 个 部 分 连 级 成 一 个 字符 串 ， 然 后 用 户 使 用 自己 的 AWS 共享 访问 密 钥 计 算出 一 
个 HMAC (Hash Message Authentication Code， 散 列 消息 校 验 码 )， 用 于 对 请 求 字 符 串 





。 Azure 存 储 
Windows Azure 提供 几 种 不 同 的 访问 Windows Azure 存储 服务 (http://msdn.microsoft. 
com/library/azure/dd179428.aspx) 的 身份 验证 方案 ， 每 一 种 都 需要 使 用 共享 密 钥 对 请 求 


。 Hawk 
这 一 新 方案 (https://github.com/hueniverse/hawk) 由 Eran Hammer 提出 ， 提 供 了 类 似 AWS 
和 Azure 的 一 种 通用 的 共享 密 钥 身份 验证 机 制 。 密 钥 不 会 在 请 求 中 直接 使 用 ， 而 是 用 于 
计算 请 求 中 的 MAC 值 。 这 样 可 以 防止 MITM (Man-In-The-Middle， 中 间 人 攻击 ) 劫持 


密 钥 。 





e OAuth 2.0 
使 用 这 种 方案 (http://tools.ietf.org/html/rfc6749)， 资 源 所 有 者 ( 即 用 户 ) 可 以 把 从 资源 
服务 器 访问 受 保护 资源 的 许可 委托 给 一 个 客户 端 。 一 个 认证 服务 器 给 这 个 客户 端 颁发 一 
个 受 限 访问 令 牌 ， 客 户 端 可 以 使 用 这 个 令 牌 访问 资源 。 这 种 方案 有 一 个 显而易见 的 优 
点 : 用 户 凭据 不 会 直接 发 送 给 试图 访问 资源 的 客户 端 应 用 程序 。 


关于 HTTP 身份 验证 机 制 和 实现 方法 (包括 OAuth) ， 请 详 见 第 15 章 和 第 16 章 。 


1.3 小 车 


本 章 大 致 介绍 了 HTTP 的 相关 背景 和 概念 。 本 章 所 介绍 的 概念 并 不 全 面 ， 只 为 帮助 你 初步 
涉猎 HTTP 这 个 资源 库 ， 为 ASP.NET Web API 开发 打下 基础 。 你 会 发 现 ， 这 里 讨论 的 每 
个 术语 都 提供 了 进一步 的 参考 信息 。 当 你 真正 开始 进行 Web API 开发 时 ， 这 些 参考 资料 会 
有 相当 的 价值 ， 因 此 ， 将 它们 收藏 在 你 的 “后 备 箱 ”中 吧 。 让 我 们 接着 学 习 Web API ! 
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第 2 章 


Web API 





Web API 不 只 是 返回 ISON 有 效 载荷 。 
在 前 一 章 ， 我 们 了 解 了 Web 以 及 HTTP (驱动 Web 的 应 用 层 协议 ) 的 核心 内 容 。 本 章 将 
讲述 Web API 的 演化 ， 介 绍 各 种 与 Web API 有 关 的 概念 ， 并 讨论 不 同 的 APL 风格 以 及 设 
计 Web API 的 方法 。 








2.1 什么 是 Web API 


Web API 是 一 个 编程 接口 ， 用 于 操作 可 通过 标准 HTTP 方法 和 标 头 访问 的 系统 。Web API 
可 供 各 种 HTTP 客户 端 使 用 ， 如 浏览 器 和 移动 设备 ， 并 可 以 使 用 Web 基础 设施 提供 的 服 
务 ， 如 缓存 和 并 发 。 














2.2 SOAP Web 服 务 


SOAP (Simple Object Access Protocol， 简 单 对 象 访 问 协议 ) 服务 不 支持 在 Web 上 使 
FA, HTTP 客户 端 ， 如 浏览 器 或 类 似 curl (参见 http://curl.haxx.se/) 这 样 的 工具 ， 调 用 
SOAP 服务 很 困难 。SOAP 请 求 必须 用 SOAP 消息 格式 正确 编写 。 客 户 端 必须 能 够 访问 
一 个 WSDL (Web Service Description Language, Web 服务 描述 语言 ) 文件 (这 个 文件 描 
述 了 SOAP 服务 提供 的 操作 )， 还 要 知道 如 何 正 确 编 写 SOAP 消息 。 这 些 限制 说 明 ， 使 用 
SOAP 服务 与 系统 进行 交互 的 语义 是 构建 在 HTTP 之 上 的 ， 而 不 是 以 其 自身 为 第 一 级 的 。 
其 次 ，SOAP Web 服务 通常 要 求 所 有 的 交互 都 通过 HTTP Post 方法 进行 ， 因 此 ， 响 应 消息 
不 能 加 以 缓存 。 再 次 ，SOAP 服务 不 允许 访问 HTTP 标 头 ， 这 极 大 地 限制 了 客户 端 ， 使 其 
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无 法 利用 HTTP 的 一 些 功能 ， 如 乐观 并 发 (optimistic concurrency) 和 内 容 协商 (content 


negotiation ) 。 


2.3 Web API 的 起 源 


2000 年 2 H, Salesforce.com 发 布 了 一 个 新 API (参见 http://history.apievangelist.com/), fÈ 
许 顾客 在 自己 的 应 用 程序 里 直接 使 用 Salesforce 的 功能 。 








随后 ， 在 同年 11 月，eBay 发 布 了 一 个 新 的 API (参见 http://investor.ebay.com/common/ 
mobile/iphone/releasedetail.cfm?ReleaseID=28230&CompanyID=ebay), R YF F R # Fill A 
eBay 的 基础 设施 ， 开 发 电子 商务 应 用 程序 。 








这 些 API FI SOAP API ( 另 一 个 新 的 趋势 ) 有 何不 同 ? 这些 Web API 针 对 的 是 第 三 方 用 
户 ， 以 支持 HTTP 的 方式 加 以 设计 。 当 时 ， 传 统 的 API 多 数 是 基于 SOAP 协议 ， 为 系统 集 
成 设计 的 。 这 些 新 API 以 纯 旧 式 的 XML 作为 消息 交换 格式 ， 使 用 纯 旧 式 的 HTTP 协议 ， 
这 使 它们 能 为 很 多 客户 端 (包括 简单 的 Web 浏览 器 等 ) 所 使 用 。 它 们 是 最 早 的 一 批 Web 
API， 之 后 又 出 现 了 很 多 别 的 类 型 。 














在 Salesfore 和 eBay 迈 出 第 一 步 后 的 儿 年 间 ， 类 似 的 API 开始 出 现 。2002 Æ, Amazon 下 
式 推 出 了 Amazon Web 服务 ， 之 后 Flickr 也 在 2004 年 推出 了 Flickr API。 





2.4 Web API 革 命 开 始 


2005 年 夏天 ，ProgrammableWeb.com 上 线 ， 其 目标 是 成 为 所 有 API 相关 产品 的 一 站 式 商 
店 。 当 时 甚 提 供 的 产品 目录 中 ， 公 共 API (SOAP 和 非 SOAP 的 ) 有 32 种 ， 相 比 2002 
年 已 经 有 了 很 大 的 增长 。 而 在 接 下 来 的 几 年 里 ， 公 共 AP 的 数量 有 了 爆炸 式 的 增长 。 这 
些 API 的 提供 者 轻 有 业界 巨头 ， 如 Facebook, Twitter, Google, LinkedIn, Microsoft 和 
Amazon， 也 有 正 处 于 起 步 阶 段 的 小 型 创业 公司 ， 如 YouTube 和 Foursquare。 到 了 2008 年 
11 月 ，ProgrammableWeb 产品 目录 中 的 API 达到 了 1000 个 。 四 年 后 ， 在 本 文 编写 时 ， 已 
经 超过 了 7000 个 ， 而 大 约 一 年 前 这 个 数目 不 过 4000 (参见 http://www.programmableweb. 
com/news/4000-web-apis-whats-hot-and-whats-next/2011/10/03)， 可 见 API 的 增长 是 加 速 进 
行 的 。 


显然 ，Web API 的 趋势 将 会 得 以 延续 。 











2.5 关注 Web 
早期 的 Web API 未 必 注 意 到 底层 的 Web 体系 结构 及 其 设计 上 的 限制 ， 从 而 导致 了 一 些 不 
良 后 果 ， 如 臭名 昭著 的 谷歌 Web 加 速 器 事件 (参见 http://boingboing.net/2005/05/06/google- 





Web API | 23 


accelerator-i.html) ， 导 致 了 顾客 数据 和 资料 的 丢失 。 


不 过 ， 近 年 来 ， 随 着 第 三 方 AP 的 使 用 者 和 设备 数量 的 快速 增长 ， 这 种 情况 得 到 了 改变 。 
各 个 组 织 机 构 意 识 到 ， 不 能 再 在 设计 API 时 忽视 Web 体系 结构 了 ， 因 为 这 样 会 带 来 负面 
影响 ， 使 其 无 法 扩大 业务 规模 、 支 持 更 多 客户 ， 也 无 法 在 不 影响 现 有 用 户 的 情况 下 改进 
API， 所 以 ， 必 须 改 变 设计 API 的 方式 。 
































Web 体系 结构 和 HTTP 会 对 Web API 的 设计 造成 影响 ， 因 此 ， 本 章 余下 的 部 分 会 对 此 进行 
简要 介绍 。 当 你 开始 使 用 APS.NET Web API 开 发 自己 的 Web API 时 ， 这 些 基础 知识 也 可 
以 帮助 你 充分 利用 Web 的 功能 。 








2.6 Web API 指 南 


这 一 节 列 出 了 一 些 指导 原则 ， 用 于 区 别 Web API 和 其 他 类 型 的 API。 通 常 来 说 ， 关 键 的 不 
同 之 处 在 于 ，Web API 是 支持 浏览 器 使 用 的 。 除 此 之 外 ，Web API 还 具有 如 下 特点 。 














。 可 供 多 种 客户 端 使 用 (至 少 支持 浏览 器 使 用 )。 

。 支持 标准 的 HTTP 方法 ,如 表 1-1 中 列举 的 方法 。API 不 必 使 用 全 部 的 HTTP 方法 ,但 是 ， 
至 少 应 该 支持 GET 以 获取 资源 ， 还 应 支持 POST 以 进行 非 安全 操作 。 

。 支持 浏览 器 友好 的 格式 。 也 就 是 说 ，Web API 支持 浏览 器 以 及 任何 其 他 HTTP 客户 端 容 
易 处 理 的 格式 。 在 技术 上 ， 浏 览 器 客户 端 可 以 使 用 XML 栈 处 理 SOAP 消息 ， 但 在 格式 
上 需要 编写 大 量 的 专门 用 于 处 理 SOAP 的 代码 。 浏 览 器 容易 处 理 的 格式 有 : XHMTL, 
JSON 以 及 Form URL 编码 。 

。 支持 浏览 器 友好 的 认证 方式 。 也 就 是 说 ， 浏 览 器 无 需 使 用 特殊 的 插件 或 扩展 ， 就 可 以 与 
服务 器 进行 认证 。 


2.7 ”特定 领域 的 媒体 类 型 

前 一 章 介 绍 了 媒体 类 型 的 概念 。 除 了 我 们 之 前 了 解 到 的 通用 的 媒体 类 型 ， 还 有 特定 领域 的 
媒体 类 型 。 这 些 特定 领域 的 媒体 类 型 带 有 丰富 的 与 特定 应 用 相关 的 语义 ， 而 Web API 要 
进行 各 种 系统 交互 而 非 简单 的 文档 传输 ， 因 此 ， 这 些 媒体 类 型 在 Web API 开发 中 的 用 处 
特别 大 。 

vCard (参见 http://tools.ietf.org/search/rfc6350) 是 一 种 特定 领域 的 媒体 类 型 ， 提 供 一 种 


标准 方式 ， 对 联系 人 信息 进行 电子 化 描述 。 很 多 流行 的 地 址 筹 和 电子 邮件 应 用 程序 ， 如 
Microsoft Outlook, Gmail 以 及 Apple Mail， 都 支持 vCard 媒体 类 型 。 
































图 2-1 展示 了 一 个 联系 人 资源 的 vCard 表示 。 








File Edit Rules Tools View Help GET /book 
ions ~ €) Any Process @A Find [al Save | Ñ GBrowse ~ Q Clear Cache JB TextWizard | - 
Web Sessions Q Statistics | 器 Inspectors | AutoResponder | [i Composer | 回 Fitters | E] Log | = Timeline 
a w | WebForms | Hexview | Auth | Cookies | Raw | JSON | XML | 
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Get SyntaxView | Transformer | Headers ||TextView | ImageView | HexView | WebView | Auth | Caching | Cookies 


IFN:Glenn Block 

|ADR;TYPE=HOME;1 Microsoft Way:Redmond:98052 
|EMAIL;TYPE=PREF, INTERNET :gblock @microsoft.com 
|END:VCARD 





Find... (press Ctrl+Enter to highlight all) 





























1/1 http: //localhost:808 1/api/contacts/1 














图 2-1: 联系 人 的 vCard 表示 


当 电子 邮件 应 用 程序 看 到 一 个 vCard 媒体 类 型 时 ， 它 马上 就 能 知道 这 是 联系 人 信息 ， 应 该 
如 何 处 理 。 如 果 这 个 电子 邮件 程序 是 要 得 到 原始 JSON 类 型 内 容 ， 由 于 JSON 媒体 类 型 没有 
定义 一 个 标准 方式 表明 “我 是 一 个 联系 人 ”， 那 么 ， 应 用 程序 就 必须 等 到 解析 ISON 内 容 之 
后 ， 才 知道 收 到 的 是 什么 信息 。 在 这 种 情况 下 ， 格 式 定义 必须 在 通信 之 外 通过 文档 来 沟通 。 
即使 这 个 格式 在 文档 中 定义 ， 也 只 会 在 这 个 应 用 中 使 用 ， 而 不 太 可 能 得 到 其 他 的 电子 邮件 
应 用 的 支持 。 而 vCard 是 一 个 标准 媒体 类 型 ， 各 种 操作 系统 的 诸多 应 用 程序 都 支持 vCard, 


随 着 应 用 程序 的 演化 和 新 需求 的 出 现 ， 我 们 可 以 遵循 IANA 注册 流程 (参见 http://www. 
iana.org/cgi-bin/mediatypes.pl) ， 创 建新 的 媒体 类 型 。 我 们 可 以 引入 新 的 媒体 类 型 ， 客 户 端 
可 以 使 用 这 些 新 的 类 型 。 而 如 前 一 章 介 绍 的 ， 客 户 端 通过 内 容 协 商 来 选择 媒体 类 型 ， 现 存 
的 客户 端 也 不 会 被 影响 ， 这 会 给 我 们 的 系统 带 来 独特 的 优势 。 


2.8 媒体 类 型 档案 


如 果 媒 体 类 型 在 很 多 客户 端 和 服务 器 中 使 用 ， 就 应 该 在 IANA 中 注册 。 但 是 如 果 一 个 媒体 
类 型 用 途 并 不 广泛 ， 只 在 一 个 应 用 程序 中 用 到 呢 ? 这 样 的 媒体 类 型 还 应 该 在 IANA 中 注册 
吗 ? 有些 人 认为 应 该 ， 但 是 ， 有 些 人 正在 尝试 使 用 更 为 轻 量 的 、 特 别 是 用 于 Web API 的 机 
制 。 媒 体 类 型 档案 使 服务 器 可 以 利用 现 有 的 媒体 类 型 (如 XML、JSON 等 )， 并 提供 包含 
特定 应 用 语义 的 附加 信息 。 

















使 用 档案 链接 关系 (profile link relation， 参 见 https://tools.ietf.org/html/rfc6906) ， 服 务 器 可 以 
在 HTTP 响应 中 返回 一 个 档案 链接 。 链 接 (link) 是 一 个 元 素 ， 其 中 至 少 包含 两 个 信息 : 描 
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述 这 个 链接 的 rel (或 关系 ) 和 一 个 URI。 对 于 档案 链接 , 链接 的 rel 值 为 profile。 链 接 中 
的 URI 不 一 定 是 可 参 引 的 ( 即 可 访问 资源 的 )， 但 很 多 时 候 这 个 URI 会 指向 一 个 文档 。 





在 今天 ， 档 案 的 使 用 存在 着 一 个 问题 : 很 多 媒体 类 型 都 不 支持 表达 链接 ， 因 此 ， 即 便 内 容 
中 包含 了 档案 信息 ， 也 不 太 可 能 为 客户 端 所 识别 。 例 如 : ISON 格式 在 Web API 中 很 常用 ， 
却 不 支持 链接 。 





幸好 ， 任 何 HTTP 响应 都 可 以 使 用 其 预先 制定 的 链接 标 头 (link header， 参 见 http://tools. 
ietf.org/html/rfc5988) 来 传递 档案 。 





在 前 面 介 绍 的 联系 人 例子 中 ， 我 们 可 以 返回 链接 标 头 ， 告 诉 客户 端 响应 中 的 内 容 不 是 任意 
一 个 原始 JSON， 而 是 用 于 example.com 的 联系 人 管理 系统 的 ISON 格式 。 如 果 客 户 端 在 
浏览 器 中 访问 链接 中 的 URI， 就 可 以 得 到 描述 有 效 载 答 的 文档 。 这 个 文档 可 以 是 任何 格式 
的 ， 例 如 ， 新 近 出 现 的 ALPS (Application-Level Profile Semantics， 应 用 级 档案 语义 ， 参 见 
htp://alps.io/spec/) 格式 ， 就 是 专 为 编写 档案 文档 而 设计 的 。 



































HTTP/1.1 200 OK 

Content-Type: application/json; charset=utf-8 

Link: <http://example.com/contactmanagement/profile>; rel="profile" 
Date: Fri, 21 Dec 2012 06:47:25 GMT 

Content-Length: 183 


{ 
"contactId":1, 
"name":"Glenn Block", 
"address":"1 Microsoft Way", 
"city":"Redmond","State": "WA", 
"Zip":"98052", 
"email": "gblock@microsoft.com", 
"twitter": "gblock", 
"self":"/contacts/1" 


2.9 多 个 表示 


一 个 资源 可 以 有 多 个 表示 ， 每 个 表示 有 着 不 同 的 媒体 类 型 。 为 了 说 明 这 一 点 ， 让 我 们 来 看 
同一 个 联系 人 资源 的 两 种 不 同 表示 。 图 2-2 展示 了 第 一 种 JSON 表示 ， 其 中 包含 了 联系 人 
信息 。 图 2-3 展示 的 第 二 种 表示 是 联系 人 的 头像 。 这 两 种 都 是 资源 状态 的 有 效 表 示 ， 但 有 
着 不 同 的 用 途 。 























客户 端 会 解析 ISON 表示 ， 获 取 其 中 数据 〈 如 联系 人 姓名 、 电 子 邮 件 地 址 等 )， 展 示 给 用 
户 。 而 PNG 表示 不 需要 解析 ， 可 以 直接 显示 。 这 是 因为 PNG 表示 是 一 个 图 像 ， 可 以 很 方 
便 地 作为 URL 传递 ， 用 在 HTML<img> 标签 里 ， 或 者 直接 用 图 像 查看 器 显示 。 正 如 之 前 的 
例子 展示 的 ， 支 持 多 个 资源 表示 的 好 处 是 : 具有 不 同 功能 的 各 种 客户 端 都 可 以 与 你 的 API 
进行 交互 。 
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File Edit Rules Tools View Help GET /book 








~ Q Clear Cache 

















= Timeline 
| son | xm | 


Request Headers 
|GET /api/contacts/1 HTTP/1.1 


# AutoResponder | 4 Composer | [C] Fiters | El tog | 
Headers | TextView | WebForms | HexView | Auth | Cookies | Raw 
Wss 20 «HTP localhost:8081 /api/contacts/1 


优 164 200 HTP localhost:8081 /api/contacts/1 

















Accept: application/json 
User-Agent: Fiddler 
Transport 
Host: localhost:8081 


Way"."Cty":"Redmond"," State": Sia op e052" cal “gblock @microsoft.com”,"Twitter”:"ablock”,"Self":"/api/contacts/1"} 











Find... (press Ctrl+Enter to highlight all) 


















































# AutoResponder | E Composer | [] Fitters | E] Log | = Timeline 
Headers | TextView | WebForms | HexView | Auth | Cookies | Raw | JSON | XML | 

Be 200 HTTP localhost:8081 /api/contacts/1 

i 200 HTP localhost:8081 /api/contacts/1 














Request Headers 
|GET /api/contacts/1 HTTP/1.1 





Accept: image/png 
User-Agent: Fiddler 
Tı 
Host: localhost:8081 


GetSyntaxview | Transformer | Headers | Textiew |Tinegevew | exiew | webven | Auth Caching 
| son | x | 



































图 2-3: 联系 人 的 PNG 表示 


2.10 API 风格 


Web API 的 构建 有 很 多 不 同 的 体系 结构 风格 。 风 格 (style) 在 这 里 是 指 在 HTTP 协议 上 实 


现 API 的 方式 。 风 格 是 设计 中 的 一 组 共同 特征 和 约束 。 每 种 风格 都 有 各 自 的 利 次 。 有 很 重 
要 的 一 点 要 注意 : 风格 是 HTTP 的 应 用 ， 而 非 HTTP 自身 。 
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例如 ， 哥 特 式 是 一 种 建筑 风格 。 因 为 哥 特 式 建筑 具有 一 些 共 同 特征 ， 如 尖 形 拱门 、 肋 状 拱 
顶 与 飞 拱 ， 所 以 你 可 以 参观 不 同 的 建筑 ， 判 断 哪 个 具有 哥 特 式 风 格 。 同 样 的 道理 ， 同 一 风 
格 的 不 同 API 也 具有 相同 的 一 组 特征 。 现 在 我 们 能 看 到 不 少 API 风格 ， 但 是 大 致 可 分 为 两 
类 : RPC 和 REST。 




















2.10.1 Richardson 成 熟 度 模型 


Leonard Richardson 提出 的 RMM (Richardson Maturity Model, Richardson 成 熟 度 模型 ， 参 
见 http://www.crummy.com/writing/speaking/2008-QCon/act3.html) 引入 了 对 API 进行 分 类 
的 一 个 框架 ， 根 据 API 如 何 利用 Web 技术 ， 将 它们 分 成 不 同 的 级 别 。 


第 0 级 ， 面 向 RPC 一 个 URI， 支 持 一 个 HTTP 方法 。 

第 1 级 ， 面 向 资源 很 多 URI， 支 持 一 个 HTTP 方法 。 

第 2 级 ，HTTP 动词 (RS URI, 每 个 URI 支持 多 个 HTTP 方法 。 
第 3 级 ， 超 媒体 ”资源 描述 自身 功能 和 交互 方法 。 


RMM 模型 最 初 被 设计 来 对 当时 存在 的 API 进行 分 类 ， 之 后 变 得 极为 流行 。 今 天 ，API tt 
区 的 很 多 开发 者 都 使 用 RMM 模型 来 对 自己 的 API 进行 分 类 。 








但 是 ， 这 个 模型 也 不 是 完美 的 。 这 个 模型 没有 建立 一 个 评分 标准 来 衡量 一 个 API 符合 
REST 的 程度 。 不 幸 的 是 ， 很 多 人 专门 利用 这 一 点 ， 把 RMM 模型 当 作 武 器 ， 攻 击 别人 的 
API 不 够 符合 REST 标准 。 这 似乎 是 连 Leonard Richardson 自己 也 不 再 推广 RMM 模型 的 原 
因 之 一 。 

















本 章 ， 你 将 进一步 了 解 RMM 模型 的 不 同 级 别 及 其 真实 的 例子 。 我 们 将 使 用 RMM 级 别 来 
讨论 APL 设计 方式 的 利 浆 。 


2.10.2 RPC (RMM 第 0 级 ) 


第 0 级 的 API 使 用 的 是 RPC (Remote Procedure Call， 远 程 过 程 调用 ) 风格 。 这 种 风格 的 
API 基 本 上 把 HITP 当 作 一 个 传输 层 协 议 ， 用 来 调用 远程 服务 器 上 的 功能 。 在 RPC 风格 
的 API 中 ，API 在 消息 的 有 效 载 符 中 加 入 自己 的 语义 ， 用 不 同 的 消息 类 型 大 和 臻 对 应 远程 对 
象 的 不 同方 法 ， 并 只 使 用 一 个 HTTP 方 法: POST。 第 0 级 的 API 的 例子 有 : SOAP 服务 、 
XML-RPC 和 POX (plain old XML), 








让 我 们 来 看 一 个 使 用 POX 的 订单 处 理 系统 示例 。 这 个 系统 提供 了 一 个 单一 订单 处 理 服务 ， 
服务 的 URL 为 : /orderService。 每 个 客户 端 向 这 个 服务 发 出 包含 不 同类 型 的 消息 ， 以 便 与 
其 进行 交互 。 


为 创建 一 个 订单 ， 客 户 端 会 发 送 如 下 请 求 : 
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POST /orderService HTTP 1.1 
Content-Type: application/xml 
Content-Length: xx 


<createOrderRequest orderNumber = "1000"> 
</createOrderRequest> 


随后 服务 器 发 回响 应 ， 告 知客 户 端 订单 创建 成 功 : 





HTTP/1.1 200 OK 
Content-Type: application/xml 
Content-Length: xx 


<createOrderResponse> 
Order created 
</createOrderResponse> 















































请 注意 : 创建 订单 操作 的 状态 不 是 通过 HTTP 状态 码 返回 的 ， 而 是 写 在 正文 中 的 。 这 是 医 
J HTTP 只 是 用 做 方法 调用 的 传输 载体 ， 所 有 的 数据 都 在 有 效 载 街中 发 送 。 
客户 端 会 发 送 一 个 get0rders 请 求 ， 以 获取 有 效 订单 列表 : 

POST /orderService HTTP 1.1 

Content-Type: application/xml 

Content-Length: xx 

<getOrdersRequest status="active"/> 

</getOrderRequest> 
服务 器 的 响应 包含 订单 列表 : 

HTTP/1.1 200 OK 

Content-Type: application/xml 

Content-Length: xx 

<getOrdersResponse> 

<orders> 
<order orderNumber = "1000" status="active"/> 
<order orderNumber = "1200" status="active"/> 
</order> 

</getOrdersResponse> 
要 批准 一 个 订单 ， 客 户 端 会 发 送 一 个 approve0rder 请 求 : 

POST /orderService HTTP 1.1 

Content-Type: application/xml 

Content-Length: xx 

<approveOrderRequest orderNumber = "1000"> 

</approveOrderRequest> 
服务 器 发 回响 应 ， 给 出 批准 的 结果 ; 
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HTTP/1.1 200 OK 
Content-Type: application/xml 
Content-Length: xx 


<approveOrderResponse> 
<error code="100">Order approval failed</error> 
<reason>Missing information</reason> 
</approveOrderResponse> 


和 之 前 提 到 的 创建 订单 的 状态 相似 ， 此 处 的 错误 码 也 写 在 消息 的 有 效 载荷 中 。 


从 这 个 示例 可 以 看 出 ，RPC 风格 的 API 使 用 有 效 载 答 摘 述 一 组 待 执 行 的 操作 及 其 结果 。 客 
户 端 清楚 地 知道 与 每 个 “服务 ”相关 的 各 种 消息 类 型 ， 并 使 用 这 些 消息 与 系统 进行 交互 。 





你 可 能 会 问 : 为 什 不 使 用 其 他 HTTP 方法 ， 如 PUT 呢 ? 原因 是 : 使 用 这 种 方式 ， 无 论 进行 
何 种 操作 ， 所 有 的 请 求 都 会 发 送 到 同一 个 端点 (/orderService)。P0ST 既 不 是 安全 方法 ， 也 
REA EEE, linia HTTP 中 定义 限制 最 少 的 一 种 方法 。 而 其 他 的 每 种 方法 都 有 额外 的 
限制 条 件 ， 无 法 满足 所 有 操作 的 要 求 。 


























这 种 API 设计 方式 有 一 个 好 处 : 非常 简单 ， 容 易 实 施 ， 也 非常 符合 已 有 的 开发 思维 模式 。 





2.10.3 资源 (RMM 第 1 级 ) 
在 RMM 第 1 级 ，API 划分 为 几 个 资源 ， 每 个 资源 通过 一 个 HTTP 方法 访问 ， 而 每 个 资源 
的 HTTP 方法 可 能 不 同 。 与 第 0 级 不 同 ， 第 1 级 API 中 的 资源 URI 表示 的 是 操作 。 





让 我 们 回 到 前 面 的 订单 处 理 示 例 ， 看 看 使 用 第 0 级 的 API 需要 发 送 何 种 请 求 。 客 户 端 为 了 
创建 一 个 订单 ， 需 要 向 createOrder API 发 送 一 个 请 求 ， 在 有 效 载 集中 传 入 订单 信息 : 














POST /createOrder HTTP 1.1 
Content-Type: application/json 
Content-Length: xx 


{ 
"orderNumber" : "1000" 


} 
之 后 ， 服 务 器 发 回响 应 ， 其 中 包含 一 个 有 效 的 订单 信息 : 


HTTP/1.1 200 OK 
Content-Type: application/json 
Content-Length: xx 


{ 
"orderNumber" : "1000", 
"status" : "active" 





客户 端 向 ListOrders 发 送 一 个 请 求 ， 指 定 查 询 条件 ， 以 便 获 取 订 单 信 息 。 


获取 操作 ， 客 户 端 实际 发 送 的 是 GET 请 求 ， 而 不 是 PosT 请 求 。 
GET /listOrders?status=active 


服务 器 返回 订单 列表 : 





HTTP/1.1 200 OK 
Content-Type: application/json 
Content-Length: xx 


{ 
[ 
{ 
"orderNumber : "1000", 
"status" : "active" 
J; 
{ 
"orderNumber" : "1200", 
"status" : "active" 
} 
] 
} 


客户 端 向 approveOrder 资源 发 送 一 个 POST 请 求 ， 来 进行 订单 批准 操作 : 


POST /approveOrder?orderNumber=1000 


请 注意 : 


使 用 这 种 风格 的 一 个 常见 API 是 Yahoo 的 Filckr API (http:/www.flickr.com/services/api/)。 阅 
读 其 文档 ， 我 们 可 以 看 到 “API Methods”。 在 galleries 分 类 下 ， 列 举 的 方法 如 图 2-4 所 示 。 


























= (S| 
eC =>) | @@ http://www. flickr.com/services/api/ P ~ BC) ee Flickr Services x | | in} 
= 
flickr.. Yaroo! The Tour Sign Up Explore Upload Fil 
Cold Fusion galleries 
© CFlickr a 
* flickr.galleries.addPhoto 
Common Lisp * flickr.galleries.create 
* Clickr * flickr.galleries.editMeta 
cur * flickr.galleries.editPhoto 
。 Cur * flickr.galleries.editPhotos 
* flickr.galleries.getinfo 
Delphi * flickr.galleries.getList 
* dFlickr * flickr.galleries.getListForPhoto 
Go * flickr.galleries.getPhotos 
* go-flickr 











2-4: Yahoo Flickr API 





Web API 


31 














有 几 个 不 同 的 URI 可 用 来 处 理 照片 。 要 添加 照片 ， 你 需要 向 addPhoto API 发 出 请 求 ， 而 获 
取 照 片 时 可 以 使 用 getPhotos。 要 更 新 照片 ， 你 可 以 使 用 editPhoto 或 editPhotos API, 











请 注意 : 在 这 种 风格 的 API 中 ， 每 个 资源 会 和 服务 器 端 对 象 的 一 个 方法 进行 对 应 ， 而 这 
还 是 非常 类 似 RPC 风格 的 。 不 同 的 是 ， 因 为 第 1 级 API 可 以 使 用 PUT 之 外 的 HTTP 方法 ， 
所 以 有 些 资 源 可 以 通过 GET 访问 ， 甚 响应 也 可 以 如 之 前 的 示例 ListOrders 那样 进行 缓存 。 
使 用 这 种 风格 还 可 以 得 到 额外 的 好 处 ， 即 可 以 方便 地 通过 增加 资源 给 系统 添加 新 的 功能 ， 
而 无 需 更 改 已 有 资源 ， 以 免 导致 现 有 客户 端 无 法 工作 。 











2.10.4 HTTP 谓词 (RMM 第 2 级 ) 

在 之 前 的 示例 中 ， 每 个 资源 都 与 服务 器 端 对 象 的 一 个 或 多 个 方法 相关 ， 和 服务 器 上 的 具体 
实现 紧密 联系 在 一 起 ， 因 此 ， 这 些 示例 都 是 面向 功能 的 (如 getorder)。 第 2 级 系统 使 用 
的 是 面向 资源 的 方式 。API 提供 一 个 或 多 个 资源 〈 如 order)， 每 个 资源 各 自 支 持 一 个 或 多 
A HTTP 方法 。 这 种 风格 的 API 在 HTTP 上 提供 更 为 丰富 的 交互 方式 ， 支 持 如 缓存 和 内 容 
协商 等 功能 。 








第 2 级 API 通常 会 区 分 集合 资源 (collection resource) 和 个 体 资源 (item resource), 





。 集合 资源 对 应 子 资源 的 集合 (如 http://example.com/orders)。 要 获取 集合 ， 客 户 端 可 以 
向 集合 资源 发 送 一 个 GET 请 求 。 要 向 集合 添加 一 个 新 成 员 ， 客 户 端 可 以 向 集合 资源 发 送 
一 个 PosT 请 求 。 

。 个 体 资源 对 应 集合 中 的 单个 子 资 源 (如 http://example.com/orders/1 对 应 订单 1) 。 要 更 新 
个 体 资源 ， 客 户 端 可 以 发 送 一 个 PUT 或 PATCH 请 求 。 要 删除 个 体 资源 ， 客 户 端 可 以 使 用 
DELETE 方法 。 使 用 PUT 方法 时 ， 如 果 待 更 新 的 资源 不 存在 ， 系 统 通常 会 允许 创建 这 个 
资源 。 个 体 资 源 也 被 泛 指 为 子 资源 (subresource)， 这 是 因为 URI 具有 层次 结构 (例如: 

££ /orders/1 中 ，1 是 orders 的 下 一 级 )。 

。 集合 资源 和 个 体 资源 都 可 以 包含 一 个 或 多 个 集合 资源 和 个 体 资 源 作为 其 下 一 级 。 


使 用 这 种 层次 风格 来 设计 订单 示例 的 API 时， 客户 端 可 以 发 送 如 下 请 求 进行 订单 的 创建 : 




















POST /orders 
Content-Type: application/json 
Content-Length: xx 


{ 
"orderNumber" : "1000" 


} 


服务 器 返回 状态 码 201 Created, MAH HY location 标 头 包含 了 新 创建 资源 的 URI, ib 
含 一 个 ETag 标 头 启用 缓存 机 制 








HTTP/1.1 201 CREATED 
Location: /orders/1000 
Content-Type: application/json 
Content-Length: xx 


ETag: "12345" 

{ 
"“orderNumber" : "1000", 
"status" : "active" 

} 


为 了 得 到 有 效 订单 列表 ， 客 户 端 向 /orders 下 的 /active 子 资源 发 送 一 个 GET 请 求 : 


GET /orders/active 
Content-Type: application/json 
Content-Length: xx 


{ 
[ 
{ 
"orderNumber : "1000", 
"status" : "active" 
J: 
{ 
"orderNumber" : "1200", 
"status" : "active" 
} 
] 
} 


客户 端 向 /order/1000/approval 发 送 一 个 PUT 请 求 ， 进 行 订单 批准 操作 : 
PUT /orders/1000/approval 


服务 器 随即 发 回响 应 ， 表 明 此 次 的 订单 批准 请 求 没有 成 功 : 





HTTP/1.1 403 Forbidden 
Content-Type: application/json 
Content-Length: xx 


{ 
"error": { 
"code" : "100", 
"message" : "Missing information" 
} 
} 


通过 上 面 的 操作 示例 ， 你 可 以 看 到 客户 端 与 第 2 级 API 的 交互 方式 有 哪些 不 同 。 客 户 端 使 
用 不 同 的 HTTP 方 法， 向 一 个 或 多 个 资源 发 出 请 求 来 表明 操作 的 意图 。 














GitHub API 是 面向 资源 API 的 一 个 真实 示例 。GitHub API (参见 https://developer.github.com/ 
v3/) 为 GitHub 中 的 每 个 主要 区 域 定 义 一 个 根 级 的 集合 资源 ， 包 括 : Orgs, Repositories, 
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Pull Requests、Issues， 等 等 。 每 个 集合 资源 都 各 有 下 一 级 的 个 体 和 集合 资源 。 你 可 以 使 用 
标准 的 HTTP 方法 与 每 个 资源 进行 交互 。 


例如 ， 要 列 出 当前 认证 用 户 的 代码 库 ， 我 们 可 以 向 repos 资源 发 送 如 下 请 求 : 


GET http://api.github.com/users/repos/ HTTP/1.1 





要 为 当前 认证 用 户 创建 一 个 新 的 代码 库 ， 我 们 可 向 同一 个 URI 发 出 POST 请 求 ， 其 中 包含 
一 个 JSON 有 效 载 午 ， 说 明 要 创建 代码 库 的 repo 信息 : 








POST http://api.github.com/users/repos/ HTTP/1.1 
Content-Type: application/json 
Content-Length: xx 


{ 
"name": "New-Repo", 
"description": "This is a new repo", 
"homepage": "https://github.com", 
"private": false, 
"has_issues": true, 
"has_wiki": true, 
"has_downloads": true 


2.10.5 ”以 资源 为 中 心 的 API 

设计 面向 资源 的 API 颇具 挑战 性 ， 因 为 以 名 词 为 中 心 / 非 面 向 对 象 的 风格 是 巨大 的 范式 转 
换 ， 与 过 去 开发 者 们 使 用 第 四 代 编 程 语言 来 设计 过 程 化 或 面向 对 象 API 的 风格 大 相 径 庭 。 
设计 面向 资源 的 API 这 一 过 程 ， 需 要 分 析 客 户 需 要 与 之 交互 的 系统 的 核心 要 素 ， 并 以 资源 
的 形式 加 以 表示 。 








API 设计 者 面 对 的 一 个 挑战 是 ， 当 现 有 的 HTTP 方法 不 能 满足 设计 和 需求 时 ， 该 如 何 处 理 ? 
例如 ， 如 果 有 一 个 Order 资源 ， 该 如 何 操作 批准 ?需要 创建 一 个 Approval HTTP 方法 吗 ? 
如 果 你 想 做 一 个 良好 的 HTTP 公民 ， 答 案 是 最 好 别 这 样 做 ， 因 为 客户 端 和 服务 器 永远 也 不 
会 料 到 要 处 理 一 个 APPROVAL 方法 。 要 解决 这 个 问题 ， 有 以 下 几 个 方法 可 供 选 择 。 


























。 让 客户 对 资源 发 送 PUT 或 PATCH 请 求 ， 在 请 求 的 有 效 载荷 中 包含 Approval=True。 可 以 
使 用 JSON 格式 ， 甚 至 直接 在 查询 字符 串 中 传 入 一 个 URL 编码 的 表单 值 也 是 可 以 的 ， 
例如 : 


PATCH http://example.com/orders/1?approved=true HTTP/1.1 





。 把 APPROVAL 定义 成 一 个 单独 的 资源 ， 让 客户 端 对 其 发 送 POST 或 PUT 请 求 : 


POST http://example.com/orders/1/approval HTTP/1.1 





2.10.6 超 媒 体 〈RMM 第 3 级 ) 

RMM 模型 的 最 后 一 级 是 超 媒 体 (hypermedia)。 超 媒体 是 响应 中 的 控件 或 自 解释 信息 ( 参 
JL http://www.amundsen.com/blog/archives/1109), ， 可 供用 户 与 相关 的 资源 进行 交互 ， 改 变 
应 用 程序 的 状态 。RMM 将 超 媒 体 定义 为 一 个 严格 的 级 别 ， 但 这 个 定义 有 些 误导 性 。 超 媒 
体 可 以 存在 于 API 中 ， 甚 至 是 面向 RPC 的 API 中 。 








Web 超 媒 体 的 起 源 


超 媒 体 和 超 文 本 是 构成 Web 和 HTTP 基础 的 两 个 概念 。Tim Berners-Lee 在 最 初 的 万 维 
网 提案 (参见 http://www.w3.org/Proposal.html) 中 这 样 定义 超 文 本 : 


“ 超 文本 以 网 状 节点 的 方式 链接 和 访问 各 种 类 型 的 信息 ， 以 供用 户 随意 浏览。 

超 文本 还 有 可 能 为 很 多 大 型 的 存储 信息 (如 报表 、 笔 记 、 数 据 库 、 计 算 机 文档 

以 及 在 线 帮 助 系统 等 ) 提供 单一 的 用 户 界面 。” 
基于 超 文本 的 这 一 概念 ，Berners-Lee 进而 提议 创建 一 个 新 的 服务 器 系统 (这 一 系统 如 
今 已 演化 为 万 维 网 ) : 

“我 们 建议 实施 一 个 简单 的 方案 ， 将 CERN 已 有 的 几 个 通过 机 器 存储 信息 的 不 

同 服务 器 合并 ,同时 通过 实验 对 信息 访问 需求 进行 分 析 。” 
超 媒体 的 概念 是 从 超 文 本 衍生 而 来 的 ， 从 简单 的 文档 扩展 到 包括 图 像 、 音 频 和 视 
w= AS. Roy Fielding 在 他 有 关 网 络 架 构 的 博士 论文 (参见 http://www.ics.uci. 
edu/~fielding/pubs/dissertation/rest_arch_style.htm) 的 第 5 章 ， 讨 论 REST (Representa 
tional State Transfer， 表 述 性 状态 转移 ) 时 ， 也 用 到 了 超 媒 体 一 词 。 他 一 开始 就 将 超 媒 
体 定义 为 REST 的 一 个 核心 组 件 : 


“本 章 介绍 并 详细 描述 了 为 分 布 式 超 媒 体系 统 设计 的 一 种 架构 风格 ， 即 表述 性 
状态 转移 (REST)。” 











超 媒 体 的 自 解释 性 信息 主要 分 为 两 大 类 : 链接 (link) 和 表单 (form)。 要 了 解 二 者 各 自 的 
作用 ， 先 来 看 一 下 HTML。 





HTML 具备 很 多 不 同 的 超 媒 体 自 解释 性 信息 ， 包 括 <A href>, <FORM> 和 <IMG> 标签 。 当 用 
户 在 浏览 器 中 查看 一 个 HTML 页 面 时 ， 会 通过 浏览 器 看 到 来 自 服务 器 的 一 组 不 同 的 链接 。 
用 户 通过 链接 的 描述 或 者 一 个 图 像 来 识别 这 些 链 接 ， 然 后 点 击 感 兴趣 的 链接 。HTML 页 面 
也 可 以 包含 表单 。 如 果 页 面 中 存在 一 个 表单 ， 如 创建 订单 用 的 那 种 表单 ， 用 户 可 以 填写 表 
单字 段 ， 然 后 点 击 “提交 ”。 在 这 两 种 情况 下 ， 用 户 都 不 需要 对 底层 URI 有 任何 了 解 ， 就 
可 以 浏览 系统 。 
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同样 地 ， 超 媒体 API 也 可 以 为 非 浏 览 器 客户 端 所 使 用 。 与 前 面 所 举 的 HTML 示例 类 似 ， 
API 的 响应 中 可 以 有 链接 和 表单 ， 但 可 用 不 同 的 格式 进行 显示 ， 如 XML 和 JSON。 要 了 
解 更 多 关于 表单 的 知识 ， 可 以 参考 CodeBetter 上 的 “Hypermedia and Forms” (参见 http:// 
codebetter.com/glennblock/2011/05/09/hypermedia-and-forms/) 。 








超 媒体 API 中 的 链接 至 少 包含 两 个 组 件 : 


。 相关 资源 的 URI; 
。 标识 链接 资源 和 当前 资源 的 关系 的 rel, 




















链接 中 的 rel (也 可 能 有 其 他 元 数据 ) 是 用 户 代理 所 关注 的 标识 符 。ret 表明 链接 所 指 的 资 
源 与 当前 资源 之 间 有 什么 关系 。 











用 H 因子 衡量 超 媒体 的 自 解释 性 


Mike Amundsen (http://amundsen.com/) 设计 了 一 个 计量 单位 : H 因子 ， 用 于 衡量 媒体 
类 型 的 超 媒 体 支持 度 。H 因子 分 为 两 组 ， 每 组 各 有 其 因子 。 


一 [LE] 眶 入 链接 
一 [LO] 外 部 链接 
一 [LT] 模板 查询 
一 [LN] aE RV AH 
一 [LI] FF VA 


。 控制 数据 支持 : 
一 [CR] 读 取 请 求 的 控制 数据 
一 [CU] 更 新 请 求 的 控制 数据 
一 [CM] 接口 方法 的 控制 数据 
一 [CL] 链接 的 控制 数据 


H 因子 是 一 种 比较 和 衡量 各 种 现 有 超 媒 体 API 类 型 的 有 效 方法 。 














回 到 订单 系统 的 例子 ， 我 们 现在 可 以 看 看 超 媒 体 是 如 何 使 用 的 。 在 前 面 提 到 的 每 个 场景 
中 ， 客 户 端 都 完全 了 解 有 哪些 URI。 但 是 ， 在 使 用 超 媒体 的 情况 下 ， 客 户 端 只 知道 一 个 
“ 根 ”URI， 它 会 访问 根 URI， 以 便 发 现 系统 中 可 获取 资源 的 信息 。 这 个 URI 的 作用 几乎 
类 似 于 一 个 主页 一 一 实际 上 ， 根 URI 就 是 一 个 主 资源 (home resource), 














GET /home 
Accept: application/json; profile="http://example.com/profile/orders" 





在 上 面 的 请 求 中 ， 客 户 端 发送 了 一 个 包含 orders 档案 的 Accept 标 头 。 








HTTP/1.1 200 OK 
Content-Type: application/json; profile="http://example.com/profile/orders" 
Content-Length: xx 


{ 
"Links" : [ 

"rel":"orders", "href": "/orders"}, 
{"rel":"shipping", "href": "/shipping"} 
{"rel":"returns", "href": "/returns"} 

] 
} 





这 个 主 资源 包含 指向 系统 其 他 部 分 的 指针 一 一 在 这 个 例子 里 ， 即 订单 、 发 货 和 退货 。 要 了 
解 如 何 与 这 些 链 接 指 向 的 资源 进行 交互 ， 编 写 客 户 端的 开发 者 可 以 参考 档案 URL 当时 指 
向 的 档案 文档 。 档 案 文 档 声明 ， 如 果 资 源 的 链接 的 rel 为 orders， 那 么 客户 端 可 以 向 资源 
发 送 一 个 订单 的 Post 请 求 ， 以 创建 一 个 新 订单 。 服 务 器 会 试图 解析 得 到 正确 的 元 素 ， 
此 ， 客 户 端 请 求 的 内 容 类 型 只 能 是 简单 的 ISON 格式 。 








客户 端 发 送 的 请 求 如 下 : 


POST /orders 
Content-Type: application/json 
Content-Length: xx 


{ 


"orderNumber" : "1000" 
} 


服务 器 发 回 的 响应 如 下 : 





HTTP/1.1 201 CREATED 

Location: /orders/1000 

Content-Type: application/json; profile="http://example.com/profile/orders" 
Content-Length: xx 


ETag: "12345" 

{ 
"“orderNumber" : "1000", 
"status" : "active" 
"Links" : [ 


{"rel":"self", "href": "/orders/1000"}, 
{"rel":"approve", "href": "/orders/1000/approval"} 
"rel":"cancel", "href": "/orders/1000/cancellation"} 
"rel":"hold", "href": "/orders/1000/hold"} 
] 
} 


注意 ， 除 了 订单 细 访 ， 服 务 器 还 会 返回 几 个 专门 适用 于 当前 订单 的 链接 : 














Web API | 37 


。 "self" 标识 这 个 订单 自己 的 URL， 可 以 用 作 这 个 订单 资源 的 书签 标记 ， 
。 "approval" 标识 用 于 批准 这 个 订单 的 资源 ; 

e "cancel" 标识 用 于 取消 这 个 订单 的 资源 ， 

。 "hold" 标识 用 于 暂停 这 个 订单 处 理 的 资源 。 

















创建 订单 成 功 后 ， 接 下 来 客户 端 就 可 以 使 用 批准 链接 ， 进 行 批准 操作 了 。 档 案 文档 说 明 ， 
客户 端 应 该 对 与 approve 的 rel 相关 的 URL 发 送 PUT 请 求 ， 批 准 订单 。 


PUT /orders/1000/approval 
Content-Type: application/json 


服务 器 返回 的 响应 与 第 2 级 API 处 理 订单 批准 请 求 的 响应 相同 。 
HTTP/1.1 403 Forbidden 


Content-Type: application/json; profile="http://example.com/profile/orders" 
Content-Length: xx 


{ 
"error": { 
"code" : "100", 
"message" : "Missing information" 
} 
} 


Paypal 最 近 发 布 了 一 个 新 的 支付 API (参见 https://developer.paypal.com/webapps/developer/ 
docs/api/) ， 在 其 响应 中 使 用 了 超 媒体 。 





























下 面 是 使 用 Paypal 新 API 进行 支付 操作 得 到 的 响应 片段 : 
"Links": [ 
{ 


"href": "https://apt.sandbox.paypal.com/v1/payments/sale/1KE480", 
"rel": "self", 


"method": "GET" 


}, 

{ 
"href": "https://apt.sandbox.paypal.com/v1/payments/sale/1KE480/refund", 
"rel": "refund", 
"method": "POST" 

}, 

{ 
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY -34629814W" , 
"rel": "parent_payment", 
"method": "GET" 

} 


如 你 所 见 ， 这 个 啊 应 中 包含 一 个 前 面 提 到 的 "self" 链接 ， 还 有 提交 退 款 操作 的 链接 和 访 
问 上 一 级 支付 的 链接 。 请 注意 : 除了 标准 的 href 和 ref 成 员外 ， 每 个 链接 还 包含 一 个 方法 
成 员 ， 建 议 客户 端 应 该 使 用 哪 种 HTTP 方法 。 在 这 个 示例 中 ，Paypal 返回 的 媒体 类 型 是 
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applLication/json， 意 味 着 客户 端 无 法 从 响应 标 头 中 看 出 这 个 响应 的 有 效 载荷 实际 上 是 一 
个 Paypal 有 效 载荷 。 尽 管 如 此 ，Paypal 的 文档 里 有 对 rel 加 以 说 明 ， 于 是 客户 端 不 需要 对 
URL 硬 编码 ， 就 能 对 系统 进行 访问 和 操作 。 








在 前 面 讨 论 的 每 个 示例 中 ， 客 户 端 都 只 需要 知道 一 个 根 URL 就 可 以 访问 API， 获 得 初始 响 
应 。 在 这 之 后 ， 客 户 端 就 通过 服务 器 提供 的 各 种 URL 来 进行 操作 。 服 务 器 可 以 随意 修改 
这 些 URL， 向 客户 端 提供 定制 的 链接 ， 而 不 会 影响 其 他 客户 端 。 这 是 使 用 超 媒体 带 来 的 好 
Kh. PR, ILE FLA BE. 


超 媒体 系统 的 实施 难度 比 别 的 系统 要 大 得 多 ， 而 且 需 要 设计 者 改变 思维 方式 。 在 实施 过 程 
中 ， 系 统 中 会 引入 更 多 可 变 的 部 分 。 此 外 ， 由 于 用 基于 超 媒 体 的 方式 进行 API 开发 是 一 门 
新 兴 的 、 演 变 中 的 “科学 ”， 因 此 ， 有 时 需要 进行 一 些 探索 性 的 工作 。 不 过 ， 在 很 多 情况 
下 ， 特 别 是 在 构建 需要 支持 很 多 第 三 方 客户 端的 开放 式 系统 时 ， 这 些 代 价 都 是 值得 的 。 





























2.10.7 REST 
REST， 即 表述 性 状态 转移 ， 可 能 是 如 今 在 Web API 开发 中 受 误解 最 多 的 术语 之 一 。 大 多 
BOGE REST 等 同 于 任何 容易 在 HTTP 上 访问 的 API， 却 完全 忘记 了 REST 的 约束 条 件 。 





这 个 词 源 自 之 前 提 到 的 Roy Fielding 的 有 关 网 络 架构 的 博士 论文 。 在 这 篇 论文 中 ，Fielding 
将 REST 描述 为 分 布 式 多 媒体 系统 的 一 种 架构 风格 。 也 就 是 说 ，REST 并 不 是 一 种 技术 、 
一 个 框架 ， 也 不 是 一 种 设计 模式 。REST 是 一 种 风格 。 实 践 REST 并 没有 唯一 正确 的 方法 ， 
因此 ，REST 风格 的 系统 具有 很 多 不 同 的 “风味 "。 但 是 ， 最 重要 的 一 点 是 ， 所 有 的 REST 
风格 的 系统 都 受到 一 系列 的 约束 。 下 一 节 将 对 此 进行 更 深入 的 介绍 。 














对 于 REST 的 另 一 个 常见 误解 是 ， 你 必须 构建 一 个 REST 风格 的 系统 。 然 而 ， 事 实 并 非 如 
此 。REST 约束 是 设计 来 创建 一 个 实现 一 组 特定 目标 的 系统 的 ， 特 别 是 一 个 能 够 长 期 演化 、 
支持 许多 不 同 的 客户 端 、 经 受 许多 不 同 的 变化 而 仍 能 支持 这 些 客户 端的 系统 。 








2.10.8 RESTAR 
REST 定义 了 如 下 6 条 约束 (其 中 一 条 是 可 选 的 )。 





。 EPRMES 
REST 系统 设计 将 用 户 界面 与 后 端 分 隔 。 客 户 端 与 服务 器 无 关 ， 于 是 二 者 可 以 独立 进行 
演化 。 


。 无 状态 
TE REST 风格 的 系统 中 ， 所 有 的 应 用 系统 状态 都 保存 在 客户 端 ， 并 在 请 求 中 传送 给 服务 
器 。 这 使 得 服务 器 不 必 单 独 记 录 每 个 客户 端的 状态 ， 就 可 以 得 到 处 理 请 求 所 需 的 所 有 信 
息 。 而 从 服务 器 端 去 除了 状态 信息 的 管理 ， 也 使 得 应 用 规模 容易 扩展 。 
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a 
WR PARAR LT EO I TEER, RERE AE PAR RETIRE 
源 服务 器 返回 已 缓存 的 表示 。 缓 存 功能 极 大 地 降低 了 延迟 ， 提 高 了 用 户 体验 的 性 能 ， 并 


且 由 于 缓存 可 以 降低 服务 器 的 负载 ， 还 提高 了 系统 的 整体 规模 。 


。 统一 接口 
REST 风格 的 系统 对 系统 交互 使 用 标准 化 的 接口 。 


。 资源 的 识别 


REST 风格 的 系统 中 ， 交 互 点 是 资源 。 此 处 的 资源 与 我 们 之 前 讨论 的 资源 概念 一 致 。 


每 个 消息 都 包含 客户 端 和 服务 器 间 进 行 交 互 所 需 的 所 有 信息 ， 包 括 URI, HTTP 方法 、 


标 头 、 媒 体 类 型 等 。 


。 通过 表示 对 资源 执行 的 操作 


前 面 已 经 介绍 过 ， 一 个 资源 可 以 有 一 个 或 多 个 表示 。 在 REST 风格 的 系统 中 ， 资 源 的 状 


态 通 过 这 些 资 源 表示 来 传递 。 


。 作为 应 用 状态 引擎 的 超 媒体 
之 前 我 们 讨论 了 超 媒 体 ， 以 及 超 媒 体 在 驱动 应 用 流 
风格 系统 的 核心 组 件 。 


。 分 层 系 统 








中 所 起 的 作用 。 这 一 模型 便 是 REST 


REST 风格 系统 中 的 组 件 是 分 层 的 ， 每 个 组 件 各 自 可 以 访问 系统 的 有 限 部 分 。 使 用 分 层 
系统 ， 可 以 在 遗留 客户 端 和 服务 器 之 间 引 入 组 件 层 ， 利 用 中 间 层 提供 附加 的 服务 ， 如 组 
存 、 实 施 安 全 策略 、 压 缩 等 ， 以 适应 客户 端 和 服务 器 的 变化 。 











。 按 需 代码 





客户 端 可 以 动态 下 载 代码 执行 ， 帮 助 客户 端 与 系统 进行 交互 。 一 个 常见 例子 是 浏览 器 中 
的 客户 端 JavaScript， 它 就 是 按 需 下 载 执行 的 。 系 统 可 以 增加 新 的 应 用 代码 ， 提 高 其 演 


化 和 扩展 能 力 。 不 过 ， 因 为 按 需 代码 会 降低 可 见 度 ， 








因此 这 条 约束 被 认为 是 可 选 的 。 


由 此 可 见 ， 构 建 一 个 REST 风格 的 系统 要 受到 诸多 约束 ， 也 不 一 定 容 易 实 现 。 关 于 REST， 


有 很 多 书 深入 讨论 了 以 上 提 到 的 问题 。 虽 然 使 一 个 系 
如 果 系 统 的 需求 符合 REST 的 设计 目标 ， 还 是 值得 做 


统 符合 REST 风格 并 不 容易 ， 但 是 ， 
努力 的 。 考 虑 到 这 个 因素 ， 这 本 书 











不 会 集中 讨论 REST， 而 是 关注 系统 的 可 演化 能 力 ， 以 及 在 构建 Web API 时 使 用 什么 技术 


来 实现 这 个 目标 。 这 些 技术 中 的 每 一 种 都 是 通 向 完全 
能 给 系统 带 来 益处 。 





REST 风格 系统 的 途径 ， 各 有 优势 ， 





换 句 话说 ， 我 们 应 该 关注 系统 的 具体 需求 ， 而 非 是 否 可 给 其 贴 上 REST 风格 的 标签 。 
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要 了 解 更 多 关于 REST 术语 的 说 明 ，Kelly Sommers 写 过 一 篇 不 错 的 博客 文章 ， 对 此 进行 
了 详细 的 阐述 (http://kellabyte.com/2011/09/04/clarifying-rest/) 。 





要 了 解 REST 风格 和 超 媒体 系统 的 构建 ， 可 以 参考 O'Reilly 出 版 的 REST in Practice 
(http://oreil.ly/rest-practice) 和 Building Hypermedia APIs with HTMLS and Node (http://oreil. 
ly/build-hyper) 。 


2.11 小 结 


本 章 ， 我 们 了 解 了 API 的 起 源 ， 探 索 了 业内 API 的 增长 ， 还 详细 讨论 了 API 分 类 。 接 下 
来 我 们 要 学 习 微 软 对 于 API 构建 的 方案 一 一 ASP.NET Web API。 下 一 章 将 介绍 ASP.NET 
Web API 框架 、 它 的 设计 目标 ， 以 及 如 何 使 用 它 进 行 API 的 开发 。 
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第 3 章 


ASP.NET Web API 101 





ARMS He. 


了 解 了 Web API 对 现代 网 络 化 应 用 的 重要 性 原委 之 后 ， 本 章 我 们 将 开始 接触 ASP.NET 
Web API。ASP.NET Web API 及 其 新 的 HTTP 编程 模型 为 构建 和 使 用 Web API 提供 了 新 的 
功能 。 我 们 将 首先 讨论 一 些 核 心 的 Web API 目标 和 支持 这 些 目标 的 功能 ， 然 后 了 解 ASP. 
NET Web API 的 编程 模型 ， 理 解 ASP.NET Web API 代码 如 何 使 用 这 些 支持 核心 目标 的 功 
能 。 当 然 ， 要 完成 这 些 任 务 ， 最 好 的 方法 就 是 查看 Visual Studio Web API 项 目 模板 提供 的 
代码 。 最 后 ， 我 们 要 修改 默认 的 模板 代码 ， 构 建 我 们 的 第 一 个 “Hello World” Web API, 


3.1 核心 场景 


与 很 多 技术 不 同 ，ASP.NET Web API 有 完善 的 、 可 访问 的 历史 记录 (其 中 一 些 记录 在 
CodePlex 上 ，http://wcf.codeplex.com/)。 从 一 开始 ，ASP.NET Web API 开发 团队 就 决定 要 
使 开发 过 程 尽 可 能 透明 ， 让 最 终 将 使 用 这 一 产品 构建 真实 系统 的 专家 们 能 够 提出 意见 ， 改 
进 产品 的 设计 。 这 一 产品 历史 可 以 精简 为 ASP.NET 致力 实现 的 核心 目标 : 






























































。 第 一 类 HTTP 编程 ， 

。 对 称 的 客户 端 和 服务 器 编程 体验 ， 
。 对 不 同 格式 的 灵活 支持 ; 

。 告别 “ 尖 括 号 编程 ”; 

。 支持 单元 测试 ， 

。 多 种 托管 选项 。 
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这 些 虽 然 是 核心 目标 ， 却 远 远 不 能 概括 ASP.NET Web API 框 架 提 供 的 全 部 功能 。 
ASP.NET Web API 将 WCF (Windows Communication Foundation) 的 精华 与 其 可 无 限 扩展 
的 架构 相 结 合 ， 将 客户 端 支 持 、 灵 活 的 托管 模型 、ASP.NET MVC (Model-View-Controller， 
模型 - 视图 - 控制 器 ) ， 与 约定 优 于 配置 、 更 好 的 可 测 试 性 、 高 级 功能 〈 如 模型 绑 定 和 验 
证 ) 结合 在 一 起 。 我 们 将 会 在 本 章 中 看 到 ，ASP.NET Web API 框架 既 简 单 易 上 手 ， 也 方便 
按 需 定 制 。 








3.1.1 第 一 类 HTTP 编 程 

在 构建 现代 Web API， 特 别 是 为 比较 简单 的 客户 端 (如 移动 设备 ) 设计 API 时， 设计 的 成 
功 与 否 经 常 与 API 的 表达 能 力 相 关 。Web API 的 表达 能 力 取决 于 它 将 HTTP 作为 应 用 协 
议 使 用 得 有 多 好 。 将 HTTP 作为 应 用 协议 使 用 ， 远 比 简 单 地 处 理 HTTP 请 求 和 生成 HTTP 
响应 复杂 得 多 。 控 制 应 用 程序 和 底层 框架 行为 的 是 HTTP 控制 流 和 数据 元 素 ， 而 不 是 仅 
仅 〈 偶 然 地 ) 通过 HTTP 传输 的 一 些 附 加 数据 。 例 如 ， 用 于 和 一 个 WCF 服务 进行 通信 的 
SOAP 请 求 : 

















POST http://localhost/GreetingService.svc HTTP/1.1 
Content-Type: text/xml; charset=utf-8 

SOAPAction: "HelloWorld" 

Content-Length: 154 


<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/enveLope/"> 
<s:Body> 
<HelloWorld xmlns="http://localhost/wcf/greeting"/> 
</s:Body> 
</s:Envelope> 





在 这 个 示例 中 ， 客 户 端 向 服务 器 发 送 一 个 请 求 ， 获 取 一 个 友好 的 问候 消息 。 如 你 所 见 ， 这 
个 请 求 是 通过 HTTP 协议 发 送 的 。 但 是 ， 这 个 请 求 与 HTTP 的 关系 也 只 是 到 此 为 止 。 这 
个 示例 中 的 API 没 有 使 用 HTTP 方法 (有 了 时 称 为 谓词 ) 来 表明 它 向 服务 请 求 的 动作 是 什 
么 ， 而 是 使 用 同一 个 HTTP 方法 一 一 P05T 一 一 发 送 所 有 的 请 求 ， 把 应 用 相关 的 细节 封装 在 
HTTP 请 求 的 正文 和 定制 的 SOAPAction 标 头 中 。 正 如 你 可 能 想到 的 ， 服 务 产生 的 响应 也 使 
用 了 同样 的 模式 : 








HTTP/1.1 200 OK 
Content-Length: 984 
Content-Type: text/xml; charset=utf-8 
Date: Tue, 26 Apr 2011 01:22:53 GMT 
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> 
<s:Body> 
<HelloWorldResponse xmlns="http://localhost/wcf/greeting"> 


</HelloWorldResponse> 
</s:Body> 
</s:Envelope> 
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和 请 求 消息 一 样 ， 控 制 应 用 的 协议 元 素 一 一 即 客户 端 与 服务 器 应 用 相互 理解 的 方式 ， 不 在 
HTTP 元 素 中 ， 而 是 分 别 放 在 请 求 和 响应 的 XML 正文 中 。 


在 这 种 方式 中 ，HTTP 没有 用 于 表达 应 用 协议 ， 而 是 简单 地 作为 裁 体 传送 另 一 个 应 用 协 
议 一 一 在 这 个 示例 中 是 SOAP。 当 一 个 服务 需要 通过 许多 不 同 的 协议 与 相似 的 客户 端 通信 
时 ， 这 种 方式 非常 适用 ， 但 是 ， 如 果 一 个 服务 需要 通过 一 种 协议 与 各 种 不 同 客户 端 通信 
时 ， 这 种 方式 就 会 产生 问题 。 对 于 Web API， 这 些 问题 尤为 典型 ， 因 为 它 不 仅 客户 端 多 种 
多 样 ， 客 户 端 和 服务 之 间 的 通信 基础 架构 (如 因特网 ) 也 各 不 相同 ， 规 模 大 且 持 续 变化 。 
在 这 个 世界 中 ， 客 户 端 和 服务 的 优化 目标 不 应 该 是 获得 协议 独立 性 ， 而 应 该 是 基于 一 个 通 
用 的 应 用 协议 创建 一 流 的 体验 。 对 于 通过 Web 进行 通信 的 应 用 来 说 ， 这 个 协议 就 是 HTTP, 























ASP.NET Web API 的 核心 是 一 组 HITP 的 原始 对 象 ， 其 中 最 重要 的 两 个 是 HttpRequest 
Message 和 HttpResponseMessage。 这 些 对 象 用 于 为 一 个 实际 的 HTTP 消息 提供 一 个 强 类 型 
的 视图 。 例 如 ， 下 面 是 一 个 HTTP 请 求 消息 : 

















GET http://localhost:50650/api/greeting HTTP/1.1 
Host: lLocalhost:50650 

accept: application/json 

if-none-match: “1” 


假设 一 个 ASP.NET Web API 服务 接收 到 这 个 请 求 ， 我 们 可 以 在 一 个 Web API 控制 器 类 中 ， 
使 用 类 似 下 面 的 代码 ， 访 问 和 操作 这 个 请 求 中 的 各 种 元 素 : 

var request = this.Request; 

var requestedUri = request.RequestUri; 

var requestedHost = request.Headers.Host; 


var acceptHeaders = request.Headers.Accept; 
var conditionalValue = request.Headers.IfNoneMatch; 


这 个 强 类 型 模型 在 HITP 之 上 提供 了 正确 层次 的 抽象 ， 让 开发 者 可 以 直接 使 用 HITP 请 求 
或 响应 ， 不 必 再 处 理 如 解析 或 生成 原始 数据 等 低层 问题 。 


3.1.2 “对称 的 客户 端 和 服务 器 编程 体验 

使 用 HTTP 对 象 库 构 建 的 ASP.NET Web API 最 吸引 人 的 一 点 是 ，HTTP 对 象 库 不 仅 可 以 在 
服务 器 端 使 用 ， 而 且 ， 还 可 以 在 使 用 NET 框架 构建 的 客户 端 使 用 。 这 意味 着 ， 这 里 提 到 
的 HTTP 请 求 ， 可 以 被 同样 的 HTTP 编程 模型 类 创建 ， 最 终 会 用 于 响应 在 Web API 内 的 请 
求 。 本 章 后 面部 分 将 会 对 此 进行 详细 介绍 。 


你 将 会 在 第 10 章 看 到 ，HTTP 编程 模型 的 功能 ， 远 不 只 是 对 请 求 和 响应 的 各 种 数据 元 素 的 
简单 操作 。HTTP 编程 模型 直接 提供 一 些 功 能 (如 消息 处 理 程 序 和 内 容 协商 )， 以 便 在 客 
户 端 和 服务 器 都 能 加 以 利用 ， 以 传递 复杂 的 客户 端 - 服务 器 交互 ， 与 此 同时 尽量 多 地 重用 
代码 。 


















































3.1.3 ”对 不 同 格式 的 灵活 支持 

第 13 章 将 对 内 容 协商 做 更 为 深入 的 探讨 ， 但 概括 地 说 ， 它 是 客户 端 和 服务 器 协同 工作 ， 
决定 在 HTTP 上 交换 资源 表示 时 使 用 的 正确 格式 的 一 个 过 程 。 进 行内 容 协商 有 几 种 不 同 的 
方式 和 技术 ，ASP.NET Web API 默认 支持 服务 器 驱动 的 方式 ， 使 用 HTTP Accept 标 头 ， 让 
客户 端 在 XML FU JSON 之 间 做 出 选择 。 如 果 请 求 中 没有 指定 Accept 标 头 ，ASP.NET Web 
API 会 默认 返回 JSON 格式 的 内 容 (和 ASP.NET Web API 框架 的 大 部 分 功能 一 样 ， 这 种 默 
认 行 为 是 可 以 改变 的 )。 





例如 ， 下 面 是 发 送 到 一 个 ASP.NET Web API 服务 的 请 求 。 
GET http://localhost:50650/api/greeting HTTP/1.1 


由 于 这 个 请 求 中 没有 Accept 标 头 告知 服务 器 客户 端 一 个 想 要 的 格式 ， 服 务 器 就 会 返回 
JSON 格式 的 内 容 。 我 们 可 以 在 请 求 中 加 入 一 个 Accept 标 头 ， 指 明正 确 的 XML 的 媒体 类 
型 标识 符 '"， 从 而 改变 服务 器 使 用 的 内 容 格式 。 





GET http://localhost:50650/api/greeting HTTP/1.1 
accept: application/xml 


3.1.4 告别 “ 尖 括号 编码 ” 

随 着 NET 框架 的 成 熟 ， 开 发 者 对 XML 配置 的 抱怨 越 来 越 多 。 为 了 实现 看 似 基 本 甚至 默 
认 的 场景 ， 开 发 者 要 进行 大 量 的 XML 配置 。 更 糟糕 的 是 ， 由 于 系统 配置 事项 ， 如 控制 运 
行 时 加 载 类 型 的 原因 ， 配 置 一 旦 修改 ， 可 能 会 导致 编译 器 无 法 发 现 的 错误 ， 只 有 在 运行 时 
才 显 现 。 一 个 显著 的 例子 是 ASP.NET Web API 的 前 身 WCF， 有 严重 的 XML 配置 问题 。 
尽管 WCF 对 自身 需要 的 配置 进行 了 精简 ， 但 是 ，ASP.NET Web API 团队 的 方向 则 截然 不 
同 ， 使 用 完全 基于 代码 的 配置 模式 。 第 11 章 将 详细 探讨 ASP.NET Web API 配置 。 


3.1.5 支持 单元 测试 

随 着 TDD (Test-Driven Development， 测 试 驱动 开发 ) 和 BDD (Behavior-Driven Development, 
行为 驱动 开发 ) 技术 的 日 益 流 行 ， 人 们 对 许多 流行 的 服务 和 Web 框架 也 产生 了 更 多 的 不 
满 。 这 些 框架 使 用 静态 的 上 下 文 对 象 、 密 封 的 类 型 以 及 多 层 继承 树 ， 使 得 人 们 很 难 脱离 底 
层 的 运行 时 进行 对 象 的 创建 和 初始 化 ， 也 不 容易 用 “ 伪 ” 实 例 蔡 换 对 象 以 更 好 的 进行 测试 
隔离 ， 于 是 ， 单 元 测试 也 就 难以 进行 。 























例如 ，ASP.NET 非常 依赖 HttpContext 对 象 ， 类 似 地 ，WCF 则 依赖 OperationContext (或 
者 WeboperationContext， 有 具体 对 象 因 服务 类 型 而 异 )。 使 用 这 种 静态 的 上 下 文 对 象 有 一 个 








注 1: 公共 媒体 类 型 目录 由 IANA (http://www.iana.org/assignments/media-types/media-types.xhtml) 维护 。 
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根本 的 问题 : 静态 对 象 是 由 各 自 框 架 的 运行 时 设置 并 依赖 这 些 运行 时 使 用 的 。 因 此 ， 如 果 
要 测试 使 用 这 种 静态 上 下 文 对 象 的 服务 ， 就 要 启动 一 个 服务 宿主 ， 运 行 这 个 服务 。 虽 然 这 
种 做 法 通常 可 以 为 集成 测试 所 接受 ， 但 是 ， 要 测试 诸如 TDD 这 样 的 驱动 开发 ， 需 要 的 是 
能 够 快速 运行 较 小 的 单元 测试 ， 这 种 测试 方法 就 不 太 适 用 了 。 











ASP.NET Web API 框架 的 目标 之 一 是 更 好 地 支持 这 些 开 发 风格 ， 框 架 的 两 个 特征 实现 了 这 
一 目标 。 第 一 个 特征 是 : ASP.NET Web API 的 编程 模型 与 MVC 框架 相同 ， 因 而 可 以 利用 
MVC 框架 在 几 年 前 实现 的 可 测试 性 功能 ， 例 如 : 使 用 抽象 机 制 ， 避 免 使 用 静态 上 下 文 对 
Ses 使 用 封装 类 ， 以 便 在 单元 测试 中 提供 “ 伪 ” 实 例 。 











第 二 个 特征 是 : ASP.NET Web API 是 以 HTTP 编程 模型 为 核心 建立 的 。 在 HTTP 编程 
模型 中 ， 对 象 的 数据 结构 简单 有 效 ， 用 户 可 以 创建 和 配置 对 象 ， 把 对 象 作为 参数 传递 给 
操作 方法 ， 还 可 以 分 析 返 回 的 方法 ， 于 是 ， 可 以 编写 简单 、 集 中 的 单元 测试 。 在 ASP. 
NET Web API 框架 的 发 展 过程 中 ， 其 团队 始终 关注 测试 ， 并 因此 在 Web API 2 中 引入 了 
HttpRequestContext。 第 17 章 将 对 这 种 可 测试 性 做 更 详细 的 介绍 。 


3.1.6 多 种 托管 选项 

WCF 虽然 有 不 少 缺 点 ， 但 也 有 很 多 优点 ， 其 中 之 一 就 是 “ 自 托管 ”功能 。 也 就 是 说 ， 
WCE 服务 可 以 在 任何 进程 中 运行 ， 例 如 : Windows 服务 、 控 制 台 应 用 程序 或 IIS (Internet 
Information Service)。 实 际 上 ， 这 种 灵活 的 托管 方式 几乎 浆 补 了 WCF 在 单元 测试 方面 的 
不 足 。 


























在 将 WCF Web API 45 ASP.NET 结合 形成 ASP.NET Web API 时 ， 开 发 团队 希望 能 够 保留 
这 种 自 托 管 功能 ， 于 是 ， 和 WCF 服务 一 样 ，ASP.NET Web API 服务 也 可 以 在 你 选择 的 任 
何 进程 中 运行 。 第 11 章 将 详细 介绍 托管 。 


3.2 ASP.NET Web APIAT] 


回顾 了 ASP.NET Web API 的 一 些 开 发 目标 后 ， 让 我 们 来 具体 了 解 创建 Web API 时 需要 使 
用 的 各 种 元 素 。 要 完成 这 项 任务 ， 最 简单 的 方法 就 是 创建 一 个 全 新 的 ASP.NET Web API 
项 目 ， 看 看 项 目 模板 有 哪些 自动 生成 。 要 创建 一 个 新 的 ASP.NET Web API 项 目 ， 你 可 以 
E “New Project” 窗 口中 ， RF “Web” WA, pf% “ASP.NET Web Application”( 参 见 
3-1)。 

















.NETFramework45 > J [Search Installed Templates (Ctrl+E) -| 














Type: Visual C# 


A project template for creating ASP.NET 
pra applications. You can create ASP.NET Web 
Forms, MVC, or Web API applications and 
Wine es add many other features in ASP.NET. 


4 Templates 


Cloud 
Reporting 
Silverlight 


> Other Languages 
> Other Project Types 
Modeling Projects 
Samples 


> Online 


Click here to go online and find templates. 
WebApplication8 
c\programming\scratch 
Create new solution 
WebApplication8 


















































图 3-1: Visual Studio 2012“New Project” 窗 口中 的 MVC4 Web Application 项 目 


选择 了 创建 ASP.NET Web 应 用 程序 之 后 ， 会 出 现 另 外 一 个 对 话 框 ， 供 你 选择 各 种 项 目 配 
置 。 在 这 个 对 话 框 中 ， 你 可 以 看 到 其 中 一 个 选项 是 创建 一 个 Web API 项 目 (参见 图 3-2). 


Be 





Select a template: 





A project template for creating RESTful HTTP services that 
mci mci pme can reach a broad range of clients including browsers and 
e e el mobile devices. 

Empty Web Forms MVC 


mir mii 
e e 
Single Page Facebook 

Application 


Learn more 











Add folders and core references for: 
C] Web Forms [Vi MVC [V] Web API 

















[C] Add unit tests 





Test project name: |WebApplication9.Tests 




















& 3-2; MVC4 New Project 对 话 框 中 的 Web API 项 目 类 型 
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在 这 个 过 程 中 ， 需 要 注意 的 关键 一 点 是 ，Web API 仅仅 是 ASP.NET 项 目 中 的 一 种 项 目 模 
板 。 这 意味 着 Web API 和 其 他 的 Web 项 目 类 型 拥有 同样 的 核心 组 件 ， 只 是 在 最 开始 为 你 
创建 的 模板 文件 上 有 所 不 同 而 已 。 这 也 说 明 ， 在 图 3-2 中 显示 的 其 他 任何 模板 中 纳入 Web 


API 都 是 合理 的 ， 也 是 人 们 希望 的 。 




















实际 上 ， 从 本 质 上 说 ，ASP.NET Web API 只 不 过 是 构建 在 Web API 框架 组 件 之 上 、 由 一 


个 进程 托管 的 一 组 类 ， 既 可 以 由 默认 模板 设置 的 ASP.NET 运行 时 托管 ， 也 可 以 由 你 
定制 的 宿主 托管 〈 本 章 稍 后 将 详细 介绍 ) 。 
不 管 是 MVC 项 目 、 控 制 台 应 用 程序 ， 还 是 在 多 个 托管 项 目 中 引用 的 类 库 。 


ASP.NET 框架 组 件 是 通过 NugGet 软件 包 管 型 











Al 














自己 





此 ，Web API 可 以 在 任何 类 型 的 项 目 中 使 用 ， 

















器 (http://docs.nuget.org/) 提供 给 你 的 Web 


API 项 目的 。 表 3-1 中 列 出 了 默认 项 目 模板 会 安装 的 NuGet 软件 包 。 要 在 自己 的 项 目 中 创 





建 Web API， 你 只 需 


表 3-1: NuGet 的 ASP.NET Web API 软 件 包 


确保 自己 安装 了 与 要 使 用 的 功能 水 平 相应 的 软件 包 。 





软件 包 名 称 Ip 描 È 依赖 包 吓 
Microsoft .NET 

是 供 核 心 HTTP 编程 模型 ， Http 
Framework 4 HTTP | Microsoft.Net.Http 提供 核 ， 编程 模型 ， 包 括 无 


Client Libraries 


RequestMessage 和 HttpResponse Message 





NuGet TE U, PEHEE ASP.NET 中 安装 




































































Microsoft ASP.NET | Microsoft.AspNet. Microsoft.AspNet. 
HEE Web API 所 需 安装 的 月 次 件 包 
Web API WebApi 和 托 和 下 需 安装 的 所 有 软件 WebApi.WebHost 
的 一 个 引 月 
Microsoft ASP.NET . 包含 核心 NET Framework 4 HTTP 客户 | . : 
i Microsoft. AspNet. | teh Microsoft.Net.Http 

Web API Client A 端 库 的 扩展 ， 以 启用 诸如 XML 和 JSON ial 

hahaa WebApi.Client pe i ap isos, Newtonsoft.Json 
Libraries 格式 化 操作 ， 以 及 内 容 协 商 等 功能 
Microsoft ASP. ye : 
ane Microsoft.AspNet. | 包含 核心 的 Web API 编程 模型 和 运行 时 | Microsoft.AspNet. 

e ore 

. . WebApi.Core 组 件 ， 如 关键 的 ApiController 类 WebApi.Client 

Libraries 
本 要 i Microsoft. Web. 

Microsoft ASP.NET | Microsoft. AspNet. | 包含 在 ASP.NET 运行 时 中 托管 Web API ; 
Web API Web Host | WebApi.WebHost | 所 需 的 全 部 运行 时 组 件 WA 

el : aH Die 

P ii i AspNet.WebApi.Core 

[a] 把 软件 包 ID 附加 到 URL http://www.nuget.org/packages/ 后 ， 可 以 获得 软件 包 的 更 多 信息 。 


[b] 当 

















[d] 在 











你 安装 一 个 软件 包 时 ，NuGet 会 首先 试 
[c] NuGet 元 包 自 身 不 包含 实际 
ASP.NET Web API 使 月 


packages/newtonsoft.json ) 。 








言 息 ， 只 包含 其 他 NuGet 软 从 
Hitt, Newtonsoft.Json 是 一 个 外 部 组 件 ， 可 以 免费 下 载 (http://www.nuget.org/ 














图 安装 这 个 软件 包 的 所 有 依赖 包 。 
F 包 的 依赖 信息 。 


除了 默认 项 目 模板 安装 的 NuGet 软件 包 之 外 ， 你 也 可 以 安装 表 3-2 中 列 出 的 NuGet 软 


件 包 。 





表 3-2: ASP.NET Web API 可 用 的 附加 NuGet 软 件 包 














软件 包 名 称 |ID 描 述 tk m 包 
Microsoft ASP. | . 包含 在 定制 进程 (如 ; 控制 台 应 用 程 
Microsoft.AspNet. o PN , , 
NET Web API . 序 ) 中 托管 Web API 所 需 的 全 部 运 | Microsoft.AspNet.WebApi.Core 
WebApi.SelfHost |,. 
Self Host 行 时 组 件 
Mi ft ASP. 是 供 在 OWIN 器 管 ASP. 
ee Microsoft.AspNet. yale L A i T Microsoft.AspNet.WebApi.Core, 
NET Web API | AON NET Web API 的 功能 ， 以 及 提供 对 J OA 
e 1.Owin ARLA icrosoit.Qwin, win 
OWIN p 其 他 OWIN 功能 的 访问 




















请 看 NuGet 软件 包 的 依赖 关系 图 (图 3-3) ， 也 许可 以 帮助 你 更 好 地 理解 如 何 根据 你 所 设想 
完成 的 目标 ， 来 决定 需要 安装 哪个 或 哪些 软件 包 。 




















图 3-3: Web API 所 需 的 NuGet 软件 包 依赖 关系 


我 们 从 这 个 依赖 关系 图 中 可 以 看 出 ， 安 装 任何 一 个 NuGet 软件 包 ， 都 会 自动 安装 图 中 与 
其 直接 或 间接 相连 的 所 有 NuGet 软件 包 。 例 如 : 安装 Microsoft.AspNet.wWebApi 会 自动 安 


装 Microsoft.AspNet.WebApi.WebHost, Microsoft.AspNet.WebApi.Core, Microsoft.Web. 





Infrastructure, Microsoft.AspNet.WebApi.Client, Newtonsoft.Json 和 Microsoft.Net. 


Http, 
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3.3 ”新建 Web API 项 目 


现在 我 们 已 经 创建 了 一 个 新 的 、Web 托管 的 ASP.NET Web API 项 目 ， 接 下 来 再 看 项 目 模 
板 创 建 的 一 些 核心 元 素 ， 我 们 会 将 对 这 些 元 素 进 行 定 制 ， 以 便 创 建 自 己 的 Web API。 我 们 





要 介绍 两 个 核心 文件 : WebApiConfig.cs 和 ValuesController.cs (参见 





区 











3-4), 





Solution Explorer 
@ o- ennaa ra 


Search Solution Explorer (Ctrl+;) 





vb 


fa) Solution 'MvcApplication8' (1 project) 
4 WW MvcApplication8 
b £ Properties 
ò we References 
国 App_Data 
4 él App_Start 
b œ BundleConfig.cs 
b œ FilterConfig.cs 
b œ RouteConfig.cs 
b ® WebApiConfig.cs 
》 国 Areas 
> imi Content 
4 ‘al Controllers 
b © HomeController.cs 
> tml Images 
国 Models 
> im Scripts 
>ò 国 Views 











3-4: Visual Studio 2013 Solution Explorer 中 的 WebApiConfig.cs 和 ValuesController.cs 文件 


3.3.1  WebApiConfig 


这 个 C# BK Visual Basic.NET 文件 位 于 顶层 目录 App_Start 下 ， 并 声明 了 它 的 WebApiconfig 
类 。WebApiConfig 只 包含 一 个 方法 Register, H global.asax 中 的 Application_Start 方法 
调用 代码 。 正 如 WebApiconfig 类 的 名 字 表 明 的 ， 这 个 类 可 用 于 注册 Web API 配置 的 各 个 方 
面 。 默 认 情 况 下 ， 项 目 模 板 生 成 的 主要 配置 代码 会 注册 一 个 默认 的 Web API 路由。 这 个 路 
由 将 收 到 的 HTTP 请 求 映 射 到 控制 器 类 ， 并 解析 URL 中 可 能 带 有 的 数据 元 素 ， 确 保 处 理 
管道 中 的 其 他 类 能 够 使 用 这 些 数 据 。 默 认 的 WebApiConfig 类 如 示例 3-1 所 示 。 


示例 3-1: 默认 的 WebApiconfig 类 
public static class WebApiConfig 





public static void Register(HttpConfiguration config) 
{ 
// Web API 配置 和 服务 





// Web API 路 由 
config.MapHttpAttributeRoutes(); 


config.Routes .MapHttpRoute( 
name: "DefaultApi", 
routeTemplate: "api/{controller}/{id}", 
defaults: new { id = RouteParameter.Optional } 
); 
} 
} 














你 如 果 精 通 MVC 开发 ， 那 么 ， 可 能 已 注意 到 ASP.NET Web API 提供 了 一 套用 于 注册 
Web API 路 由 的 扩展 方法 ， 与 默认 的 MVC 路 由 不 同 。 例 如 ， 这 个 新 项 目 在 WebApiconfig 
类 之 外 ， 还 包含 下 面 的 类 : 


public class RouteConfig 


{ 


public static void RegisterRoutes(RouteCollection routes) 


{ 


routes .IgnoreRoute("{resource}.axd/{*pathInfo}"); 


routes .MapRoute( 
name: "Default", 
url: "{controller}/{action}/{id}", 
defaults: new { controller = "Home", action = "Index", 

id = UrlParameter.Optional } 
); 
} 
} 


一 个 项 目 有 两 个 路 由 注册 方法 这 一 点 ， 乍 看 之 下 有 些 让 人 不 知 所 以 ， 因 此 ， 有 必要 解释 
一 下 二 者 的 大 臻 区别。 有 一 点 要 记 住 的 是 ， 这 些 “ 上 映射 ”方法 只 是 扩展 方法 ， 创 建 一 个 
路 由 实例 ， 并 把 这 个 实例 添加 到 与 宿主 相关 的 路 由 集合 之 中 。ASP.NET MVC 和 ASP. 
NET Web API 的 区 别 及 其 原因 ， 在 于 它们 使 用 的 路 由 类 不 同 ， 甚 至 路 由 集合 的 类 型 也 不 
相同 。 第 11 章 会 对 这 些 类 型 的 细节 进行 更 多 讨论 ， 但 是 ，ASP.NET Web API 之 所 以 使 用 
与 ASP.NET MVC 不 同 的 路 由 类 型 ， 是 为 了 能 够 尽量 脱离 System. Web 程序 集 里 与 Route 和 
RouteCollection 类 相关 的 遗留 代码 ， 从 而 提供 更 为 灵活 的 托管 选项 。 这 种 设计 带 来 的 直接 
好 处 就 是 ，ASP.NET Web API 的 自 托 管 能 力 。 























配置 ASP.NET Web API 路 由 ， 需 要 声明 HttpRoute 实例 并 添加 到 路 由 集合 中 。 虽 然 创建 
HttpRoute 实例 的 扩展 方法 和 ASP.NET MVC 中 的 不 同 ， 但 是 ， 两 个 方法 的 语义 几乎 一 样 ， 
都 使 用 相同 的 元 素 ， 如 路 由 名 、 路 由 模板 和 默认 参数 ， 甚 至 都 使 用 路 由 约束 。 正 如 你 在 示 
Bil 3-1 中 看 到 的 ， 项 目 模板 的 路 由 配置 代码 设置 了 一 个 默认 的 API 路由， 路 由 的 URI 前 绥 
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为 





“api”， 后 面 接 控制 器 名 和 一 个 可 选 的 ID 参数 。 这 个 路 由 配置 不 需要 进行 任何 修改 ， 就 


足以 用 来 创建 提供 获取 、 更 新 和 删除 数据 功能 的 API。 这 种 路 由 配置 之 所 以 如 此 灵活 ， 是 
因为 ASP.NET Web API 控制 器 类 把 HTTP 方法 映射 到 控制 器 的 操作 方法 使 其 成 为 可 能 。 
本 章 后 文 以 及 第 12 章 将 更 详细 地 介绍 HTTP 方法 映射 。 


3. 














3.2 ValuesController 


ApiController, BH ValuesController 的 父 类 ， 是 ASP.NET Web API 的 核心 。 虽 然 只 需 实 


现 





IHTTPController 接口 的 各 种 成 员 ， 就 可 以 创建 一 个 可 用 的 ASP.NET Web API 控制 器 


但 在 实际 使 用 中 ， 大 部 分 ASP.NET Web API 的 控制 器 还 是 通过 继承 ApiController sos 


的 。 


ApiController 类 负责 协调 ASP.NET Web API 对 象 模型 中 各 个 不 同 的 类 ， 在 HTTP 请 


求 的 处 理 中 执行 一 些 关 键 的 任务 : 





选择 和 运行 控制 器 类 上 的 一 个 操作 方法 ; 

将 HTTP 请 求 消息 的 各 元 素 转换 成 控制 器 操作 方法 的 参数 ， 并 将 操作 方法 的 返回 值 转换 
成 有 效 的 HTTP IEX; 

Tate iE as, AS ie as AEAN Es E E E, HT ee Je s 
rah et et een ii ia， 


Web API 模板 中 的 ValuesController 类 ， 继 承 了 ApiController 类 并 利用 其 执行 的 关键 处 














理 任务 ， 呈 现 出 Apicontroller 之 上 的 更 高 层次 的 抽象 。 示 例 3-2 展示 了 ValuesController 


代码 。 


示例 3-2: 默认 的 ValuesController 类 


public class ValuesController : ApiController 
{ 

// GET api/values 

public IEnumerable<string> Get() 


{ 
} 


return new string[] { "value1", "value2" }; 


// GET api/values/5 
public string Get(int id) 
{ 


} 


return "value"; 


// POST api/values 

public void Post([FromBody]string value) 
{ 

} 


// PUT api/values/5 
public void Put(int id, [FromBody]string value) 





} 


// DELETE api/values/5 
public void Delete(int id) 
{ 
} 

} 


这 个 ValuesController 类 ， 虽 然 简单 ， 却 让 我 们 第 一 次 接触 到 了 控制 器 编程 模型 。 


首先 要 注意 的 是 控制 器 中 操作 方法 的 命名 。 默 认 情况 下 ，ASP.NET Web API 采用 传统 方 
式 ， 在 一 定 程度 上 通过 比较 HTTP 方法 名 和 操作 方法 名 来 选择 执行 哪个 操作 方法 。 更 准确 
地 说 ，ApiControtLter 会 寻找 名 字 以 相应 的 HTTP 方法 开头 的 控制 器 操作 方法 。 因 此 ， 在 
示例 3-2 中 ， 发 送 到 /api/values 的 HTTP GET 请 求 会 触发 控制 器 中 无 参数 的 Get() 方法 。 
ASP.NET Web API 框架 提供 不 同 的 方法 定制 修改 默认 的 名 字 匹 配 逻辑 ， 并 提供 扩展 点 ， 如 
果 你 需要 的 话 可 以 完全 替换 这 套 逻 辑 。 第 12 章 将 详细 介绍 控制 器 和 方法 选择 机 制 。 


ASP.NET Web API 除了 可 以 根据 HTTP 方法 来 选择 操作 方法 ， 还 可 以 根据 请 求 的 其 他 元 
素 ， 如 如 查询 字符 串 参数 来 进行 选择 。 更 重要 的 是 ，ASP.NET Web API 框架 支持 从 请 求 元 
素 到 操作 方法 参数 的 绑 定 。 默 认 情 况 下 ，ASP.NET Web API 框架 结合 各 种 方法 的 使 用 来 实 
现 参数 绑 定 ， 采 用 的 算法 既 支持 简单 NET 类 型 ， 也 支持 复杂 NET 类 型 。 对 于 HTTP 响 
PE, ASP.NET Web API 编程 模型 允许 操作 方法 返回 NET 类 型 ， 使 用 内 容 协商 将 这 些 返回 
值 转换 成 适当 的 HTTP 响应 消息 正文 。 第 13 章 将 详细 介绍 参数 绑 定 和 内 容 协 商机 制 。 


到 目前 为 止 ， 我 们 讨论 了 一 些 ASP.NET Web API 的 设计 特点 ， 通 过 项 目 模板 提供 的 代码 ， 
简单 了 解 了 其 编程 模型 。 接 下 来 让 我 们 更 进一步 创建 第 一 个 Web API。 























3.4 “Hello Web API!” 


我 们 的 第 一 个 ASP.NET Web API 是 一 个 简单 的 问候 服务 。 在 计算 机 编程 文化 中 ， 还 有 什 
么 问候 能 比 “Hello World!” 更 无 处 不 在 呢 ? 因此 ， 我 们 将 从 这 个 简单 的 只 读 问 候 API 开 
始 ， 然 后 通过 本 章 的 剩余 部 分 增加 一 些 改进 ， 演 示 ASP.NET Web API 编程 模型 的 其 他 
方面 。 





3.4.1 创建 服务 

要 创建 服务 ， 你 只 需 在 Visual Studio 的 New Project 对 话 框 中 ， 选 择 创 建 一 个 新 的 ASP. 
NET Web Application。 在 Web Application Refinement 对 话 框 中 ， 选 择 Web API. Visual 
Studio 就 会 使 用 默认 模板 创建 一 个 新 的 ASP.NET Web API 项 目 。 





1. 一 个 只 读 的 问候 服务 
我 们 要 在 默认 的 Web API 项 目 模板 中 ， 加 入 一 个 新 的 控制 器 。 要 加 入 新 控制 器 ， 你 可 以 
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添加 一 个 新 的 类 ， 或 者 使 用 Visual Studio 的 控制 器 模板 。 如 果 使 用 模板 添加 控制 器 ， 











你 


可 以 在 Solution Explorer 中 右键 点 击 Controllers 目录 ， 在 弹出 的 右键 菜单 中 选择 Add 一 








Controller (参见 图 3-5). 











® View in Browser (Internet Explorer) 
Browse With... 
Convert to Web Application 
© Check Accessibility... 
Add 
Scope to This 
New Solution Explorer View 
Exclude From Project 
% Cut 
GI Copy 
Paste 
X Delete 
X= Rename 
© Open Folder in Windows Explorer 
* = Properties 








HomeController.cs 
ValuesController.cs 









> B Controller... CtrleM, Ctrl+C 

T Newltem... Ctrl+Shift+A 
W Biisting Item... Shift+Alt+A 
Ha New Folder 

Ctri+X Add ASP.NET Folder » 

Cul+C Class... 

Be 

Del 


Alt+Enter 

















3-5; 添加 新 控制 器 的 Visual Studio 右键 菜单 


在 弹出 的 对 话 框 中 ， 你 可 以 填 和 要 创建 的 控制 器 的 更 多 配置 细节 。 我 们 要 创建 的 控制 器 名 








为 GreetingController， 使 用 Empty API controller 模板 (参见 图 3-6). 











Controller name: 
|GreetingController 
Scaffolding options 
Template: 
[Empty API controller 


None 





Add Controller | x | 


| Add || Cancel 























3-6: 创建 Web API 控制 器 


填 完 事项 模板 对 话 框 之 后 ，Visual Studio 会 新 建 一 个 GreetingController 类 ， 继 承 
ApiControLter。 为 了 让 我 们 的 新 API 返回 一 个 简单 的 问候 ， 我 们 需要 给 控制 器 添加 一 个 方 
法 ， 对 HTTP GET 请 求 做 出 响应 。 请 记 住 ， 按 照 默 认 的 路 由 规则 ，GreetingController 会 
在 HTTP 请 求 发 给 api/greeting 时 使 用 。 因 此 ， 我 们 要 添加 一 个 简单 的 方法 ， 对 GET 请 求 


进行 处 理 : 











| 大 
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public class GreetingController : ApiController 
{ 


public string GetGreeting() { 
return "Hello World!"; 
} 


} 





现在 可 以 测试 一 下 ， 看 看 这 个 Web API 是 否 真 的 会 返回 我 们 的 简单 问候。 要 进行 测试 ， 我 


们 要 使 用 HTTP 调试 代理 工具 Fiddler (http://www.fiddler2.com/), Fiddler 的 一 个 对 Web 
API 测试 特别 有 帮助 的 功能 是 ， 它 可 以 构造 并 执行 HTTP 消息 。 我 们 可 以 使 用 Fiddler 的 这 
个 功能 测试 问候 API， 操 作 界 面 如 图 3-7 所 示 。 




















EI TIE 可 cm | Elem TE teo [= meee | 





























GET v |http: /locathost:50650/api/sreetng [Hry v 
Request Headers [Upload file...] Help... 
User-Agent: Fiddier 
ip @ 3-7: 使 用 Fiddler 构造 一 个 新 的 HTTP 请 求 
电 在 执行 这 个 请 求 时 ， 我 们 可 以 使 用 Fiddler 的 会 话 查 看 器 来 浏览 请 求 和 啊 应 消息 ， 操 作 界 面 
如 图 3-8 所 示 。 
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图 3-8: 使 用 Fiddler 检查 HTTP 请 求 和 响应 消息 
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发 送 到 问候 服务 的 这 个 简单 的 HTTP GET 请 求 返 回 了 字符 串 “Hello World!”， 测 试 通过 。 


2. 内 容 协 商 

让 我 们 再 回头 仔细 看 一 下 图 3-8 中 ，HTTP 响应 消息 的 Content-Type 标 头 。 在 默认 情况 下 ， 
ASP.NET Web API 使 用 图 3-3 中 介绍 常见 的 Json.NET 类 库 ， 将 操作 方法 的 返回 值 转换 成 
JSON 格式 。 但 是 ， 正 如 本 章 之 前 介绍 的 ，ASP.NET Web API 支持 服务 器 驱动 的 内 容 协 
商 ， 并 且 ， 默 认 支 持 选 择 ISON 和 XML 其 中 一 个 。 为 了 了 解 内 容 协商 的 功能 ， 我 们 回 到 
Fiddler 的 请 求 消 息 编辑 器 ， 在 请 求 标 头 文本 框 中 添加 一 行 : 





accept: application/xml 


再 次 执行 这 个 请 求 ， 你 会 看 到 响应 销 息 现 在 包含 标 头 Content-Type: application/xml, #4 
在 的 响应 正文 为 XML 格式 (参见 图 3-9) 。 
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string xminse"http: //schenas microsoft, com/2003/10/Sertalization/">Hello world!</strt 
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[r+ ~ (press Cel sEsher to highlight all) 

















83-9: 进行 内 容 协商 的 基本 问候 API 的 请 求 和 响应 消息 


3. 添加 一 个 问候 

以 不 同 的 格式 返回 一 句 问候 确实 很 有 意思 ， 但 是 ， 有 实际 用 途 的 API 都 需要 能 够 操作 系统 
的 状态 或 数据 。 因 此 ， 我 们 要 扩展 问候 服务 ， 让 用 户 可 以 添加 新 的 问候 语 。 用 户 可 以 指定 
一 个 问候 名 和 问候 消息 ， 添 加 到 服务 中 ， 之 后 可 以 通过 一 个 包含 问候 名 的 URL 来 GET 这 
个 问候 消息 。 另 外 ， 如 果 用 户 由 于 拼写 错误 或 其 他 原因 没有 在 URL 中 指定 正确 的 问候 名 ， 
我 们 还 需要 返回 一 个 HTTP 404 状态 码 ， 告 诉 用 户 未 找到 请 求 的 资源 。 


要 让 用 户 在 服务 器 上 创建 一 个 新 的 问候 ， 我 们 需要 先 创建 一 个 模型 类 ， 用 于 保存 问候 的 名 
字 和 消息 属性 。 可 以 在 项 目的 Models 文件 夹 中 添加 如 下 的 类 : 





























public class Greeting 


public string Name { 
get; 
set; 





} 


public string Message { 
get; 
set; 


} 





接 下 来 ， 我 们 要 在 GreetingController 类 中 添加 一 个 操作 方法 ， 用 于 处 理 HTTP POST 请 
求 ， 这 个 方法 的 参数 是 Greeting 实例 。 


这 个 操作 把 参数 中 传 入 的 问候 添加 到 一 个 静态 列表 中 ， 返 回 一 个 带 着 Location 标 头 的 
HTTP 状态 码 201， 指 向 新 创建 问候 的 URL。 有 了 这 个 Location 标 头 ， 客 户 端 就 可 以 直接 
通过 这 个 链接 值 访问 新 创建 的 问候 资源 ， 而 不 用 自己 构建 URL， 而 因为 服务 器 URL 结构 
可 能 会 随时 发 生变 化 ， 使 用 返回 的 资源 URL 就 会 使 客户 端 适应 性 更 强 。 




















public static List<Greeting> _greetings = new List<Greeting>(); 


public HttpResponseMessage PostGreeting(Greeting greeting) { 
_greetings.Add(greeting); 


var greetingLocation = new Uri(this.Request.RequestUri, 

"greeting/" + greeting.Name); 
var response = this.Request.CreateResponse(HttpStatusCode. Created); 
response.Headers.Location = greetingLocation; 


return response; 


} 


向 静态 集合 添加 新 问候 之 后 ， 我 们 创建 了 一 个 URI 实例 来 表示 它 的 地 址 ， 以 便 在 之 
后 的 请 求 中 能 找到 这 个 新 问候 。 接 着 ,我们 使 用 HttpRequestMessage 实例 的 工厂 方法 
CreateResource (这 个 方法 由 基 类 ApiController 提供 )， 创 建 一 个 新 的 HttpResponse 
Message。 在 操作 方法 内 部 使 用 HTTP 对 象 模型 实例 ， 是 ASP.NET Web API 的 核心 功能 

一 。 使 用 这 一 功能 ， 开 发 者 可 以 对 HTTP 消息 元 素 (如 Loation 标 头 ) 进行 细 粒 度 的 控制 ， 
又 不 依赖 于 诸如 HttpContext 或 WebOperationContext 这 样 的 静态 上 下 文 对 象 。 这 一 点 在 提 
高 Web API 控制 器 的 可 测试 性 方面 特别 有 用 ， 接 下 来 我 们 会 加 以 讨论 。 

















最 后 ， 我 们 要 给 GetGreeting 方法 添加 一 个 过 载 方法 ， 取 得 并 返回 客户 提供 的 定制 问候 : 





public string GetGreeting(string id) { 
var greeting = _greetings.FirstOrDefault(g => g.Name == id); 
return greeting.Message; 


} 





文 个 方法 很 简单 ， 只 要 找到 第 一 个 Name 属性 和 传人 的 id 参数 匹配 的 问候 ， 然 后 返回 这 个 
问候 的 Message 属性 。 需 要 注意 的 是 ， 现 在 这 个 方法 没有 对 id 参数 进行 任何 输入 验证 。 下 
一 节 将 对 此 进行 讨论 。 
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在 默认 情况 下 ，HTTP POST 消息 的 正文 由 一 个 MediaTypeFormatter 对 象 进行 处 理 ， 这 个 对 
象 是 根据 Content-Type 请 求 的 标 头 信 息 所 选择 的 。 相 对 应 地 ， 我 们 下 面 展 示 的 这 个 HTTP 
请 求 ， 将 由 默认 的 JSON 格式 化 程序 处 理 ， 使 用 Json.NET 将 JSON 字符 串 反 序列 化 ， 生 成 
Greeting 类 的 一 个 实例 : 

POST http://localhost:50650/api/greeting HTTP/1.1 

Host: localhost:50650 


Content-Type: application/json 
Content-Length: 43 


{"Name": "TestGreeting","Message":"Hello!"} 


随后 ， 这 个 生成 的 实例 将 被 传递 给 PostGreeting 方 法 ， 添 加 到 问 修 集合 中 。 在 
PostGreeting 处 理 完 请 求 后 ， 客 户 端 将 得 到 如 下 的 HTTP 响应 : 


HTTP/1.1 201 Created 
Location: http://localhost:50650/api/greeting/TestGreeting 


根据 HTTP 响应 中 的 Location 标 头 信息 ， 客 户 端 就 可 以 接着 发 送 请 求 ， 访 问 这 个 新 问候 : 


GET http://localhost:50650/api/greeting/TestGreeting HTTP/1.1 
Host: lLocalhost:50650 





和 最 开始 的 只 读 问候 服务 一 样 ， 客 户 端 可 预期 返回 如 下 响应 : 


HTTP/1.1 200 OK 
Content-Type: application/json; charset=utf-8 
Content-Length: 8 


"Hello!" 


4. 错误 处 理 

只 要 服务 器 不 发 生 任何 错误 ， 并 且 所 有 的 客户 端 都 遵循 同样 的 规则 和 约定 ， 前 面 提 到 的 
HTTP 消息 交换 就 能 有 效 进行 。 但 是 ， 如 果 服 务 器 出 错 或 者 收 到 无 效 的 请 求 ， 会 出 现 什 么 
情况 呢 ? 在 这 方面 ， 创 建 和 使 用 HITP 对 象 模型 实例 的 能 力 起 到 了 很 大 的 作用 。 在 示例 
3-3 中 ， 我 们 希望 操作 方法 根据 问候 名 返回 其 字符 串 。 如 果 没 有 找到 所 请 求 的 问候 名 ， 我 
们 希望 返回 一 个 带 有 HTTP 状态 码 404 的 响应 。 为 了 实现 这 种 功能 ，ASP.NET Web API 提 
供 了 HttpResponseException 类 。 












































示例 3-3: 无 法 找到 问候 时 返回 一 个 404 状态 码 
public string GetGreeting(string id) { 
var greeting = _greetings.FirstOrDefault(g => g.Name == id); 
if (greeting == null) 
throw new HttpResponseException(HttpStatusCode.NotFound) ; 
return greeting.Message; 








在 找 不 到 问候 名 时 ， 直 接 返 回 一 个 新 的 、 包 含 状 态 码 404 的 HttpResponseMessage 也 是 合理 
的 ， 但 是 ， 这 种 处 理 方式 要 求 GetGreeting 操作 方法 总 是 返回 一 个 HttpResponseMessage, 
会 使 非 异 和 ith pa 部 分 的 代码 路 径 变 得 过 于 复杂 ， 而 这 是 没有 必要 的 。 男 外 ， 啊 应 消 
息 需 要 经 过 整个 Web API 管道 ， 这 在 异常 发 生 时 也 很 可 能 是 没有 必要 的 。 考 虑 到 这 
些 因 素 ， a 作 方 法 中 发 出 一 个 HttpResponseException， 而 不 是 返回 一 个 
HttpResponseMessage。 如 果 需 要 让 异常 包含 一 个 支持 内 容 协商 的 响应 正文 ， 那 么 ， 你 可 以 
使 用 控制 器 基 类 的 Request.CreateErrorResponse 方法 生成 一 个 HttpResponseMessage， 传 
递 给 HttpResponseException 的 构造 国 数 。 





























5. 测试 
直接 使 用 HTTP 对 象 模 型 而 非 静 态 上 下 文 对 象 ， 带 来 一 个 额外 的 好 处 ， 使 你 可 以 对 Web 
API 控制 器 编写 有 意义 的 单元 测试 。 第 17 章 将 详细 介绍 有 关 测 试 的 内 容 ， 但 是 ， 在 这 个 介 
绍 性 的 示例 中 ， 还 是 让 我 们 为 6reetingController 的 PostGreeting 操作 方法 快速 编写 一 个 
单元 测试 : 








[Fact] 
public void TestNewGreetingAdd() 
{ 
// 准备 
var greetingName = "newgreeting"; 
var greetingMessage = "Hello Test!"; 
var fakeRequest = new HttpRequestMessage(HttpMethod.Post, 
"http: //Localhost:9000/api/greeting"); 
var greeting = new Greeting { Name = 
greetingName, Message = greetingMessage }; 


var service = new GreetingController(); 
service.Request = fakeRequest; 


// 操作 


var response = service.PostGreeting(greeting) ; 


// 断言 

Assert.NotNuLll(response) ; 

Assert.Equal(HttpStatusCode.Created, response. StatusCode) ; 

Assert.Equal(new Uri("http://localhost:9000/api/greeting/newgreeting"), 
response.Headers.Location) ; 


} 


这 个 测试 遵循 单元 测试 编写 的 标准 模式 一 一 准备 - 操作 — ITT (arrange, act, assert), $ 
们 创建 一 些 控制 状态 (包括 一 个 新 的 HttpRequestMessage 实例 ) ， 以 表示 整个 HTTP 请 求 ， 
然后 使 用 上 下 文 调用 测试 的 方法 ， 最 后 对 响应 进行 一 些 断 言 。 在 这 个 测试 中 ， 响 应 是 一 个 
HttpResponseMessage 实例 ， 由 此 ， 我 们 可 以 对 响应 自身 的 数据 元 素 进行 断言 。 
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3.4.2 客 Am 

正如 本 章 开 始 提 到 的 ， 围 绕 一 个 核心 HTTP 编程 模型 构建 ASP.NET Web API， 还 有 一 个 重 
要 的 好 处 : 同样 的 编程 模型 也 可 以 用 于 为 客户 端 和 服务 器 构建 极 好 的 HTTP 应 用 。 例 如 ， 
我 们 可 以 使 用 如 下 代码 构建 一 个 请 求 ， 由 第 一 个 GetGreeting 操作 方法 处 理 : 

















class Program 


{ 


static void Main(string[] args) 


{ 
var greetingServiceAddress = 
new Uri("http://localhost:50650/api/greeting"); 


var client = new HttpClient(); 
var result = client.GetAsync(greetingServiceAddress) .Result; 
var greeting = result.Content.ReadAsStringAsync().Result; 


Console.WriteLine(greeting) ; 


} 


和 在 服务 器 上 一 样 ， 这 里 的 客户 端 代码 可 以 创建 和 处 理 HttpRequestMessage 和 
HttpResponseMessage 实例 。 另 外 ，ASP.NET Web API 扩展 组 件 ， 如 媒体 类 型 格式 化 程序 
和 消息 处 理 程序 ， 既 可 以 在 服务 器 端 使 用 ， 也 可 以 在 客户 端 使 用 。 








3.4.3 ”宿主 


开发 一 个 在 传统 ASP.NET 应 用 中 托管 的 ASP.NET Web API， 和 创建 任何 其 他 类 型 的 ASP. 
NET MVC 应 用 的 方式 非常 相似 。 然 而 ，ASP.NET Web API 的 一 大 特点 是 ， 它 可 以 托 
管 在 你 指定 的 任何 进程 中 ， 而 几乎 不 需要 为 此 做 额外 的 工作 。 示 例 3-4 展示 了 将 我 们 的 
GreetingController 托管 于 一 个 定制 宿主 进程 (在 这 个 示例 中 是 控制 台 应 用 程序 ) 所 需 的 
代码 。 











示例 3-4: 一 个 简单 的 Web API 控制 台 宿 主 
class Program 
{ 
static void Main(string[] args) 
{ 
var config = new HttpSelfHostConfiguration( 
new Uri("http://localhost:50651")); 


config.Routes .MapHttpRoute( 
name: "DefaultApi", 
routeTemplate: "api/{controller}/{id}", 
defaults: new { id = RouteParameter.Optional }); 


var host = new HttpSelfHostServer (config); 





host.OpenAsync().Wait(); 


Console.WriteLine("Press any key to exit"); 
Console.ReadKey(); 


host.CloseAsync() .Wait(); 
} 
} 
如 果 要 用 一 个 定制 进程 托管 Web API， 我 们 不 需要 修改 控制 器 ， 也 不 需要 在 app.config X 
件 中 添加 任何 神奇 的 XML 配置 。 实 际 上 , 我 们 只 要 创建 一 个 HttpSefHostConfiguration 实 
例 ， 配 置地 址 和 路 由 信息 ， 然 后 开启 这 个 宿主 。 一 旦 宿主 开启 并 监听 请 求 ， 我 们 就 阻塞 
主 控制 台 线程 ， 从 而 防止 服务 器 关闭 。 当 用 户 选 择 关 闭 宿 主 时 ( 按 任意 键 )， 我 们 就 关闭 
Web API 宿主 ， 退 出 控制 台 应 用 程序 。 第 11 章 将 详细 讨论 托管 机 制 。 


3.5 小结 


本 章 ， 我 们 描述 了 ASP.NET Web API 的 一 些 关 键 设 计 目 标 ， 然 后 用 Web API 项 目 模板 展 
示 了 组 成 框架 的 不 同 组 件 如何 通 过 NuGet 组 织 和 发 布 ， 并 且 利 用 默认 的 模板 代码 探索 了 框 
架 的 编程 模型 。 最 后 ， 我 们 编写 了 “Hello World!” Web API， 还 使 用 了 ASP.NET Web API 
的 自 托管 功能 。 


从 第 4 章 开 始 ， 后 面 的 章节 将 对 本 章 介 绍 的 各 个 主题 逐一 进行 深入 地 探讨 。 第 4 章 将 探索 
ASP.NET Web API 的 底层 工作 机 制 。 
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第 4 章 


MERE 





现在 来 讨论 些 完全 不 同 的 东西 。 


前 一 章 讨论 了 核心 ASP.NET Web API 的 编程 模型 ， 介 绍 了 显示 在 框架 中 的 一 系列 基础 概 
念 、 接 口 和 类 。 在 开始 讨论 这 本 书 的 核心 主题 ， 即 可 演化 的 Web API 设计 之 前 ， 本 章 要 
绕 个 弯 子 先 审视 其 底层 机 制 ， 探 究 ASP.NET Web API 的 内 部 机 制 ， 展 现 底层 的 处 理 架 构 ， 
详细 介绍 在 收 到 HTTP 请 求 和 返回 相应 的 HTTP 响应 信息 之 间 发 生 了 什么 。 本 章 也 可 以 用 
作 一 张 路 线 图 ， 帮 你 初步 了 解 这 本 书 第 三 部 分 将 要 介绍 的 ASP.NET Web API 高 级 功能 

















在 本 章 中 ,我们 将 以 示例 4-1 的 HTTP 请 求 ， 结 合 示 例 4-2 中 的 控制 器 作为 一 个 具体 例子 ， 
说 明 ASP.NET Web API 处 理 架 构 的 运行 时 行为 。ProcessesController 控制 器 包含 一 个 
GET 操作 ， 这 个 操作 返回 一 个 表示 ， 包 含 指定 图 像 名 称 的 所 有 进程 。 示 例 中 的 HTTP GET 请 
求 的 对 象 是 被 In 标识 的 资产， 这 个 党 
源 代表 了 所 有 正在 运行 的 浏览 器 进程 。 








示例 4-1: HTTP 请 求 消息 示例 
GET http://localhost:50650/api/processes?name=explorer HTTP/1.1 
User-Agent: Fiddler 
Host: localhost:50650 
Accept: application/json 


示例 4-2: 控制 器 示例 
public class ProcessesController : ApiController 


{ 


public ProcessCollectionState Get(string name) 


{ 
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if (string.IsNullOrEmpty(name)) 
{ 


} 


return new ProcessCollectionState 


{ 


throw new HttpResponseException(HttpStatusCode.NotFound) ; 


Processes = Process 
. GetProcessesByName(name) 
.Select(p => new ProcessState(p)) 
}; 


} 


public class ProcessState 


{ 
public int Id { get; set; } 
public string Name { get; set; } 
public double TotalProcessorTimeInMillis { get; set; } 


public ProcessState() { } 
public ProcessState(Process proc) 


{ 
Id = proc.Id; 
Name = proc.ProcessName; 
TotalProcessorTimeInMillis = proc. TotalProcessorTime. TotalMilliseconds; 


} 


public class ProcessCollectionState 


{ 
J 


public IEnumerable<ProcessState> Processes { get; set; } 


图 4-1 展示 的 ASP.NET Web API 处 理 架 构 分 为 三 层 。 





。 托管 (hosting) 层 ， 位 于 Web API 和 底层 的 HTTP 栈 之 间 。 

。 消息 处 理 程序 管道 (message handler pipeline) 层 ,可 以 用 于 实现 横 切 关注 点 (cross-cutting 
concern)， 如 日 志和 缓存 。 但 是 ，OWIN (http:/owin.org/， 将 在 第 11 章 中 介绍 ) 的 引 
入 将 消息 处 理 程序 管道 的 一 些 功 能 下 移 到 了 栈 下 端的 OWIN 中 间 件 中 。 

。 控制 器 处 理 (controller handling) 层 ， 控 制 器 和 操作 是 在 这 一 层 进行 调用 的 ， 参 数 在 此 
绑 定 和 验证 , HTTP 响应 消息 也 在 这 创建 。 此 外 , 这 一 层 还 包含 和 执行 算 选 器 管道 (filter 
pipeline) 。 
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定制 托管 


4-1; 简化 的 ASP.NET Web API 处 理 模 型 











接 下 来 将 对 这 些 层次 逐一 进行 介绍 。 


4.1 托管 层 


Web API 处 理 构 架 的 最 底层 负责 API 托管 ， 是 Web API 和 底层 HTTP 基础 结构 的 接口 ， 例 
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an; 经 典 的 ASP.NET 管道 、.NET Framework 的 System 程序 集中 的 HttpListener, 或 一 个 
OWIN 宿主 。 托 管 层 负责 创建 HttpRequestMessage 实例 ， 表 示 HTTP 请 求 ， 然 后 将 其 推送 
到 上 层 的 销 息 处 理 程序 管道 。 在 处 理 响应 时 ， 托 管 层 还 负责 获取 从 消息 处 理 程序 管道 返回 
的 HttpResponseMessage 实例 ， 把 它 转换 成 可 由 底层 网 络 栈 处 理 的 响应 消息 


























请 记 住 ，HttpRequestMessage 和 HttpResponseMessage 是 .NET Framework 4.5 中 引入 的 代表 
HTTP 消息 的 新 类 。 这 两 个 新 类 是 Web API 处 理 架 构 的 核心 ， 托 管 层 的 主要 任务 就 是 ， 在 
这 两 个 类 和 底层 HTTP 协议 栈 使 用 的 本 地 消息 表示 之 间 建 立 连接 。 


在 我 们 编写 本 书 时 ，ASP.NET Web API 支持 几 种 不 同 的 托管 层 ， 分 别 是 : 
































。 在 任何 Windows 进程 (例如 ,控制 台 应 用 程序 或 Windows 服务 ) 中 的 自 托管 (self-hosting ) ; 
e Web 托管 (Web hosting)， 即 在 互联 网 信息 服务 (IS) 之 上 使 用 ASP.NET 管道 
。 OWIN 托管 (使 用 OWIN 兼容 的 服务 器 ， 如 Katana) '。 





一 种 托管 方法 建立 在 WCF 的 自 托管 功能 之 上 ， 第 10 章 将 对 此 进行 更 详细 的 介 


第 二 种 方法 Web 托管 一 一 使 用 了 ASP.NET 的 管道 和 路 由 功能 ， 将 HTTP 请 求 转发 
到 一 个 新 的 ASP.NET 处 理 程序 ，HttpControllerHandler 中 。 这 个 处 理 程序 将 收 到 的 
HttpRequest 实例 转换 成 HttpRequestMessage 实例 ， 然 后 推送 到 Web API 管道 ， 从 而 在 传 

统 的 ASP.NET 管道 和 新 的 ASP.NET Web API 架构 间 建 立 起 了 连接 。 这 个 处 理 程序 还 负责 
获取 Web API 返回 的 HttpResponseMessage 实例 ， 将 其 复制 为 HttpResponse 实例 ， 然 后 传 
递 给 下 层 的 ASP.NET 管道 。 





























第 三 种 托管 方法 ， 是 在 一 个 OWIN 兼容 的 服务 器 上 建立 一 个 Web API 层 。 使 用 这 种 方法 
v 托管 层 把 OWIN 上 下 文 对 象 转换 成 一 个 新 的 HttpRequestMessage #4 发 送 给 Web 
I。 反 过 来 ， 托 管 层 也 会 把 Web API 返回 的 HttpResponseMessage 写 人 OWIN EFX. 





还 有 第 四 种 方法 ， 就 是 完全 不 用 托管 层 ，Httpclient 使 用 与 Web API 同样 的 类 模型 ， 直 
接 发 送 请 求 给 Web API 运行 时 ， 无 需 进行 任何 转换 。 第 11 章 将 对 托管 层 进行 更 深层 次 的 
探讨 。 


4.2 ”消息 处 理 程 序 


Web API 处 理 架 构 的 中 间 层 是 消息 处 理 程 序 管 道 。 这 一 层 提供 了 一 个 扩展 点 ， 拦 截 器 可 以 
在 这 里 处 理 横 切 关注 点 ， 如 日 志和 缓存 。 这 一 层 在 作用 上 与 框架 中 间 件 的 概念 类 似 ， 如 
Ruby 的 Rack (参见 http://rack.rubyforge.org/doc/SPEC.html)、Python 的 WSGI (Web Server 
Gateway Interface, Web 服务 器 网 关 接 口 ， 参 见 http://legacy.python.org/dev/peps/pep-3333/) 


和 Node.js Connect Framework (http://www.senchalabs.org/connect/) 。 


























iE 1: ASP.NET Web API # 2 版 中 引入 了 OWIN 托管 支持 。 
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消息 处 理 程序 是 对 一 个 操作 的 抽象 ， 它 接受 HTTP 请 求 消息 (HttpRequestMessage 实例 ) 
并 返回 HTTP 响应 消息 (HttpResponseMessage 实例 )。ASP.NET Web API 消息 处 理 程序 管 
道 是 这 种 处 理 程序 的 组 合 ， 管 道中 的 每 个 程序 (最 后 一 个 除外 ) 都 有 指向 下 一 个 程序 的 指 
针 ， 这 个 指针 称 为 内 部 处 理 程序 (inner handler)。 使 用 这 种 管道 组 织 方式 ，Web API 能 够 
执行 的 操作 就 具有 了 很 大 的 灵活 性 ， 如 图 4-2 所 示 。 
















HttpRequestMessage : HttpResponseMessage 
InnerHandler 


HttpRequestMessage HttpResponseMessage HttpRequestMessage HttpResponseMessage 


















4-2: 消息 处 理 程序 流程 示例 


图 左 侧 展示 了 如 何 使 用 处 理 程序 ， 对 请 求 和 响应 消息 分 别 执行 一 些 预 处 理 和 处 理 后 操作 。 
通过 InnerHandter， 处 理 流 程 从 一 个 处 理 程序 移动 到 另 一 个 ， 一 个 方向 的 流程 进行 请 求 消 
息 处 理 ， 反 方向 进行 响应 消息 处 理 。 以 下 是 一 些 预 处 理 和 处 理 后 操作 的 例子 : 


。 在 控制 器 的 操作 方法 处 理 消 息 之 前 ， 根 据 请 求 消息 是 否 包 含 某 个 标 头 (如 X-HTTP- 
Method-0verride) ， 改 变 请 求 的 HTTP Wis; 

。 添加 一 个 响应 标 头 ， 如 Server, 

。 获取 和 记录 诊断 信息 或 业务 指标 数据 。 


你 可 以 使 用 处 理 程序 直接 产生 一 个 HTTP 响应 ， 提 前 终止 管道 流程 ， 如 图 4-2 右 侧 所 示 。 
通常 采用 这 种 做 法 的 情况 是 ， 当 请 求 消息 没有 得 到 正确 地 身份 验证 ， 立 即 返回 一 个 状态 码 
为 401 (Unauthorized) 的 HTTP 响应 。 





























在 NET 框架 中 ， 消 息 处 理 程序 是 新 抽象 类 HttpMessageHandler 的 派生 类 ， 类 的 层次 关系 
如 图 4-3 所 示 。 














f MessageProcessingHandler y } 
Abstract Class | 
| + DelegatingHandler 

‘器 


i DelegatingHandler A ] 
| Abstract Class | 
| > HttpMessageHandler | 

局 了 | 


IDisposable 
Í HttpMessageHandler A | 
| Abstract Class | 
i 了 | 
| 日 Methods | 


®©, SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) : Task<HttpResponseMessage> f 














? IDisposable 中 IDisposable 


p 


( HttpRequestMessage y HttpResponseMessage 
Class Class 























4-3: 消息 处 理 程序 的 类 层次 





抽象 方法 SendAsync 接收 一 个 HttpRequestMessage 实例 ， 通 过 返回 Task<HttpResponse Message>, 
异步 生成 一 个 HttpResponseMessage。 这 个 方法 遵循 TAP (Task-based Asynchronous Pattern, 
基于 任务 的 异步 模式 ， 参 见 http://msdn.microsoft.com/en-us/library/hh873175.aspx) 关于 取 
消 操作 的 原则 ， 也 接受 CancellationToken 实例 。 


按照 我 们 刚才 对 消息 处 理 程序 管道 组 织 的 描述 ， 消 息 处 理 程 序 需要 有 一 个 数据 成 员 ， 保 
存 指 向 一 个 内 部 处 理 程序 的 指针 和 数据 流 逻 辑 ， 把 请 求 和 响应 消息 从 一 个 处 理 程序 委 
托 给 它 的 内 部 处 理 程序 。 这 些 附 加 信息 在 DelegatingHandler 类 中 实现 ， 这 个 类 定义 了 
InnerHandler 属性 ， 将 一 个 处 理 程序 连接 到 其 内 部 处 理 程序 。 











在 ASP.NET Web API 配 置 对 象 模型 中 ，HttpConfiguration.MessageHandLers 集合 属性 
定义 了 消息 处 理 程序 委托 的 顺序 (例如: config.MessageHandlers.Add(new TraceMessage 
Handler());)。 管 道中 消息 处 理 程序 的 顺序 与 config.MessageHandlers 集合 中 的 顺序 一 致 。 





ASP.NET Web API 2.0 引入 了 OWIN 模型 支持 ， 提 供 OWIN 中 间 件 作为 消息 处 理 程序 的 
可 选 方 式 ， 实 施 横 切 关注 点 。OWIN 中 间 件 的 主要 优点 是 ，OWIN 中 间 件 不 是 专门 与 Web 








处 理 架 构 | 67 





API 绑 定 的 ， 因 而 可 以 与 其 他 Web 框架 (40 ASP.NET MVC 或 SignalR) 一 起 使 用 。 例 如 ， 
Web API 2.0 中 引入 的 新 的 安全 功能 (参见 第 15 章 ) ， 大 部 分 作为 OWIN 中 间 件 实现 ， 并 
可 以 在 Web API 之 外 重用 。 另 一 方面 ， 消 息 处 理 程序 也 可 以 在 客户 端 重用 ， 第 14 章 将 对 
此 进行 介绍 。 


路 由 分 发 


在 消息 处 理 程序 管道 的 未 端 ， 有 两 种 特殊 的 处 理 程序 。 








。 路 由 分 发 器 (routing dispatcher) ; 由 HttpRoutingDispatcher 类 实现 。 
。 控制 器 分 发 器 (controller dipatcher) : 由 HttpControllerDispatcher 类 实现 。 


路 由 分 发 器 处 理 程 序 执行 下 列 操作 。 


。 从 消息 中 获取 路 由 数据 (例如 ， 使 用 Web 托管 时 ) 或 者 执行 之 前 没有 执行 的 路 由 解析 
(例如 ， 使 用 自 托管 时 )。 如 果 没 有 找到 符合 条 件 的 路 由 ， 处 理 程序 就 产生 一 个 状态 码 为 
404 Not Found 的 响应 消息 。 

。 使 用 路 由 数据 ， 根 据 匹配 的 IHttpRoute 来 选择 转发 请 求 所 用 的 下 一 个 处 理 程序 。 


控制 器 分 发 器 处 理 程序 负责 执行 下 列 操作 。 











。 使 用 路 由 数据 和 控制 器 选择 程序 (controller selector) ， 获 得 一 个 控制 器 描述 (controller 
description) 。 如 果 没 有 找到 控制 器 描述 ， 处 理 程序 就 返回 一 个 状态 码 为 494 Not Found 
的 响应 消息 。 

。 获取 控制 器 实例 ， 调 用 控制 器 的 ExecuteAsync 方法 ， 传 入 请 求 消息 。 

。 处 理 控制 器 返回 的 异常 ， 将 其 转换 为 状态 码 为 505 Internal Error 的 响应 消息 。 








例如 ， 如 果 使 用 示例 4-1 中 的 HTTP 请 求 和 默认 的 路 由 配置 ， 路 由 数据 就 上 只 包含 一 个 
带 controller 键 和 process 值 的 接口 。 这 个 路 由 数据 接口 是 通过 匹配 请 求 URL (http:/ 
localhost:50650/api/processes?name=explorer) 和 路 由 模板 (/api/{controller}/{id}) 得 到 的 。 


默认 情况 下 ， 路 由 分 发 程序 把 请 求 消息 转发 给 控制 器 分 发 程序 ， 然 后 控制 器 分 发 程序 会 调 
用 控制 器 。 但 是 ， 我 们 也 可 以 直接 定义 一 个 单 路 由 处 理 程序 (per-route handler), ， 如 图 4-4 
所 示 。 

















元 金 胡同 的 处 理 


默认 情况 








图 4-4: 单 路 由 处 理 程序 和 路 由 分 发 处 理 程序 


对 于 单 路 由 处 理 ， 请 求 会 转发 到 一 个 由 此 路 由 定义 的 处 理 程序 ， 而 不 是 默认 的 控制 器 分 发 
程序 。 使 用 单 路 由 分 发 的 原因 之 一 ， 是 需要 让 请 求 消息 通过 一 个 特殊 路 由 的 处 理 程 序 管 
道 。 例 如 ， 对 不 同 的 路 由 ， 通 过 消息 处 理 程序 实现 时 ， 会 采取 不 同 的 身份 验证 方法 。 使 用 
单 路 由 分 发 的 另 一 个 原因 ， 是 用 来 蔡 换 非 ASP.NET 的 Web API 顶层 框架 (控制 器 处 理 ) 。 


ra 

4.3 控制 器 处 理 

ASP.NET Web API 处 理 架 构 的 最 后 、 也 是 最 上 一 层 是 控制 器 处 理 。 这 一 层 负责 从 底层 的 管 
道 接收 请 求 信 息 ， 转 换 为 对 控制 器 操作 方法 的 调用 ， 并 传递 需要 的 方法 参数 。 控 制 器 处 理 
层 还 负责 把 操作 方法 的 返回 值 转换 成 响应 消息 ， 回 传 给 消息 处 理 程序 管道 。 




















连接 消息 处 理 程序 管道 和 控制 器 处 理 层 的 桥梁 是 控制 器 分 发 程序 。 控 制 器 分 发 还 是 一 个 消 
息 处 理 程序 ， 主 要 任务 是 选择 、 创 建 和 调用 正确 的 控制 器 来 处 理 请 求 。 第 12 章 将 详细 讨 
论 控 制 器 分 发 的 过 程 ， 介 绍 所 有 与 这 个 过 程 相关 的 类 ， 展 示 如 何 使 用 可 用 的 扩展 点 修改 默 
认 行 为 。 
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ApiControLLer 基 类 


最 终 处 理 请 求 的 那个 具体 控制 器 ， 


可 以 直接 实现 IHttpController 接口 。 但 是 ， 正 如 之 前 




















一 章 介 绍 的 ， 通 常 的 做 法 是 从 抽象 类 ApiController 进行 派生 ， 生 成 具体 的 控制 器 ， 如 图 
4-5 所 示 。 
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4-5: 从 抽象 类 Apicontroller 派生 出 具体 的 控制 器 类 


ApiController.ExecuteAsync 负责 根据 HTTP 请 求 方法 (如 GET 或 POST) 选择 适当 的 操作 ， 
并 调用 派生 的 具体 控制 器 上 的 相关 方法 。 例 如 ， 示 例 4-1 中 的 GET 请 求 会 分 发 给 Process 
Controller.Get(string name) 方法 。 


在 选择 操作 之 后 ， 调 用 相关 方法 之 前 ，ApiController 类 会 执行 第 选 器 管道 (Filter 
Pipeline) ， 如 图 4-6 所 示 。 每 个 操作 都 有 自己 的 管道 ， 具 有 如 下 功能 : 


。 BRAVE; 


。 把 操作 返回 值 转换 为 HttpResponseMessage; 
。 身份 验证 、 授 权 和 操作 科 选 器 ， 


。 异常 筛选 器 。 
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图 4-6: ENRI EE, DMAE ERRAR 


1. 参数 绑 定 
参数 绑 定 就 是 计算 操作 的 参数 值 ， 在 调用 操作 的 方法 时 会 用 到 。 图 4-7 展示 了 参数 绑 定 的 
过 程 。 参 数 绑 定 使 用 来 自 几 个 地 方 的 信息 ， 分 别 是 : 


。 路 由 信息 (如 路 由 参数 ) ; 

。 请 求 URI 查询 字符 串 ， 

。 请 求 正文 ; 

。 请 求 标 头 。 

在 执行 一 个 操作 的 管道 时 ，ApiController .ExecuteAsync 方法 将 调用 一 系列 HttpParameterBinding 


实例 ， 每 个 实例 与 操作 方法 的 一 个 参数 相关 。 每 个 HttpParameter Binding 实例 会 计算 一 
个 参数 值 ， 把 参数 值 添 加 到 HttpActionContext 实例 的 Action Arguments 字典 中 。 
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4-7: 参数 绑 定 


HttpParameterBinding 是 一 个 抽象 类 ， 其 上 派生 出 多 个 有 具体 类 ， 每 个 具体 类 对 应 一 种 
参数 绑 定 。 例 如 ，FormatterParameterBinding 类 使 用 请 求 正 文 内 容 和 一 个 格式 化 程序 
(formatter) 获得 参数 值 。 


格式 化 程序 是 抽象 类 MediaTypeFormatter 的 扩展 类 ， 在 CLR (Common Language Runtime, 
通用 语言 运行 时 ) 类 型 和 因特网 媒体 类 型 (参见 hetp://www.iana.org/assignments/media- 
types/media-types.xhtml) 定义 的 字 节 流 表示 之 间 进 行 双向 转换 。 图 4-8 展示 了 这 些 格式 化 
程序 的 功能 。 


另 一 种 参数 绑 定 是 ModeLBinderParameterBinding 类 ， 这 个 类 使 用 模型 绑 定 (model binder) 
的 概念 ， 采 用 一 种 类 似 ASP.NET MVC 的 方式 ， 从 路 由 数据 取得 信息 。 例 如 ， 对 于 示例 
4-2 中 的 操作 和 示例 4-1 中 的 HTTP 请 求 ，GET 方法 中 的 name 参数 会 绑 定 到 值 explorer, 
也 就 是 查询 字符 串 条 目 中 键 为 name 的 值 。 第 13 章 将 更 详细 地 介绍 格式 化 程序 、 模 型 绑 定 
和 验证 。 
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MediaTypeFormatter (+ 1 overload) 
ReadFromStreamAsync (+ 1 overload) 
SelectCharacterEncoding 
SetDefaultContentHeaders 
WriteToStreamAsync (+ 1 overload) 





图 4-8: 格式 化 程序 以 及 消息 正文 与 CLR 对 象 间 的 转换 








2. 转换 为 HttpResponseMessage 

操作 方法 的 结果 可 能 是 任何 对 象 ， 在 操作 方法 结束 之 后 ， 结 果 返 回 到 筛选 如 管道 之 前 ， 这 个 
操作 结果 必须 转换 为 HttpResponseMessage。 如 果 返 回 值 类 型 可 以 赋值 给 IHttpActionResult 接 
口 ”( 参 见 示例 4-3)， 那 么 系统 就 调用 这 个 结果 的 ExecuteAsync 方法 ， 将 其 转换 为 一 个 响应 
信息 。IHttpActionResult 接口 有 好 几 种 实现 可 以 在 操作 方法 的 代码 中 使 用 ， 如 OkResult 和 
RedirectResult, ApiController 基 类 中 也 有 几 个 受 保护 方法 (图 4-5 中 没有 展示 )， 可 以 由 派 
生 类 调用 ， 构 建 IHttpActionResult 的 实现 (如 protected internal virutal OkResult OK()), 





示例 4-3: IHttpActionResult 接口 
public interface IHttpActionResult 


{ 
J 


Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken); 


如 果 操 作 方 法 的 返回 值 不 是 IHttpActionResutt， 那 么 系统 会 选用 一 个 实现 了 示例 4-4 中 定 
义 的 TActionResultConverter 接口 的 外 部 结果 转换 程序 ， 生 成 啊 应 消息 。 


示例 4-4: 结果 转换 程序 ”将 操作 的 返回 值 转换 为 响应 消息 


public interface IActionResultConverter 





{ 

HttpResponseMessage Convert( 
HttpControllerContext controllerContext, 
object actionResult); 

} 





注 2: Web API 版 本 2.0 中 引入 了 IHttpActionResult 接口 。 
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对 于 示例 4-1 中 的 HTTP 请 求 ， 选 中 的 结果 转换 程序 会 试 








图 找到 一 个 能 够 读 取 Process 


CollectionState ( 即 操作 方法 返回 值 的 类 型 ) 的 格式 化 程序 ， 生 成 application/json ( 即 
请 求 消息 Accept 标 头 的 值 ) 格式 的 字 节 流 表示 。 最 终 ， 生 成 的 响应 消息 如 示例 4-5 所 示 。 


示例 4-5: HTTP 响应 


HTTP/1.1 200 OK 

Cache-Control: no-cache 

Pragma: no-cache 

Content-Type: application/json; charset=utf-8 
Expires: -1 

Server: Microsoft-IIS/8.0 

Date: Thu, 25 Apr 2013 11:50:12 GMT 
Content-Length: (...) 


{"Processes":[{"Id":2824,"Name":"explorer", 
"TotalProcessorTimeInMillis" :831656.9311}]} 


第 13 章 将 详细 讨论 格式 化 程序 和 内 容 协商 。 


3. 筛选 器 


示例 4-6 中 列 出 的 接口 定义 了 身份 验证 、 授 权 和 操作 筛选 右 ， 这 些 盘 选 器 和 消 息 处 至 
的 作用 相似 ， 即 实现 横 切 关注 点 (如 身份 验证 、 授 权 和 验证 )。 


示例 4-6: 筛选 器 接口 


public interface IFilter 


{ 
} 


bool AllowMultiple { get; } 


public interface IAuthenticationFilter : IFilter 
{ 
Task AuthenticateAsync( 
HttpAuthenticationContext context, 
CancellationToken cancellationToken) ; 


Task ChallengeAsync( 
HttpAuthenticationChallengeContext context, 
CancellationToken cancellationToken) ; 


} 


public interface IAuthorizationFilter : IFilter 


{ 


Task<HttpResponseMessage> ExecuteAuthorizationFilterAsync( 


HttpActionContext actionContext, 
CancelLlationToken cancellationToken, 
Func<Task<HttpResponseMessage>> continuation); 


} 


public interface IActionFilter : IFilter 


{ 


Task<HttpResponseMessage> ExecuteActionFilterAsync( 








HttpActionContext actionContext, 
CancellationToken cancellationToken, 
Func<Task<HttpResponseMessage>> continuation); 


} 
public interface IExceptionFilter : IFilter 
{ 

Task ExecuteExceptionFilterAsync( 
HttpActionExecutedContext actionExecutedContext, 
CancellationToken cancellationToken) ; 

} 














对 于 授权 和 操作 筛选 器 ， 其 管道 的 组 织 和 消息 处 理 程序 管道 类 似 : 每 个 筛选 器 都 有 指向 管 
道中 下 一 个 算 选 器 的 指针 ， 能 够 对 请 求 和 响应 执行 预 处 理 和 后 处 理 。 除 了 这 种 执行 方式 
外 ， 往 选 器 也 可 以 产生 一 个 新 响应 ， 从 而 取消 之 后 的 处 理 〈 即 调用 这 个 操 
作 )。 身 份 验证 筛选 器 的 工作 模型 稍微 有 些 不 同 ， 第 15 章 将 对 此 进行 介绍 。 


se ae a FAL Gi WE eee ES BAB EZ BUD. MERE 
Lee anions age KE, BEE RIEL AEA TD Bek, A IQS By ETE 

道 早 期 执行 的 操作 ， 例 如 ， 如 果 没 有 得 到 授权 则 立刻 产生 一 个 
返回 得 为 401 (Not Authorized) 的 HTTP 响应 消息 。 另 一 方面 ， 操 作 往 选 器 则 适合 那些 需 
要 访问 已 绑 定 参数 的 操作 。 
































第 四 种 筛 选 器 类 型 ， 异 常 得 选 器 ， 只 有 当 筛 选 器 管道 返回 的 Task<HttpResponseMessage> 
状态 错误 时 ( 即 发 生 异 常 时 ) 才 使 用 。 每 个 异常 筛选 器 都 按 顺 序 调用 ， 都 有 机 会 创建 一 个 
HttpResponseMessage， 进 行 异 常 处 理 。 回 想 一 下 ， 如 果 控 制 器 分 发 程序 收 到 一 个 未 处 理 的 
异常 ， 就 会 返回 一 个 状态 码 为 500 (Internal Server Error) AY HTTP 响应 消息 。 


我 们 可 以 采取 多 种 方式 将 筛选 器 关联 到 控制 器 或 操作 : 


。 通过 属性 ， 与 ASP.NET MVC 支持 的 方式 类 似 ， 
e 使 用 Httpconfiguration.Filters 集合 ， 明 确 地 将 和 饰 选 器 实例 注册 到 配置 对 和 象 ， 
。 在 配置 服务 的 容器 中 ， 注 册 IFilterProvider 的 实现 。 

















HttpResponseMessage 实例 离开 操作 管道 之 后 ， 就 由 ApiController 返回 给 控制 器 分 发 处 理 程 
序 ， 然 后 在 消息 处 理 程序 管道 中 逐步 下 行 ， 最 后 由 托管 层 转 换 成 一 个 本 地 的 HTTP 响应 。 











4.4 ”小 结 


这 本 书 的 第 一 部 分 到 这 里 就 结束 了 ， 这 一 部 分 的 目标 是 介绍 ASP.NET Web API， 它 存在 的 

原因 、 基 本 编程 模型 以 及 核心 处 理 架构 。 掌 握 了 这 些 知 识 ， 在 这 本 书 的 下 一 部 分 ， 我 们 将 
把 注意 力 转移 到 如 何以 ASP.NET Web API 为 支持 平台 ， 设 计 、 实 现 和 使 用 可 演化 的 Web 
API 上 。 
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第 二 部 分 





真实 世界 的 AP| 开 发 


第 5 章 


应 用 程序 





要 么 演化 ， 要 么 消亡 。 


到 目前 为 止 ， 我 们 讨论 了 构建 Web API 所 需 的 工具 。 我 们 讨论 了 HTTP 协议 的 概念 、 使 用 
ASP.NET Web API 的 基础 知识 ， 以 及 Web API 架构 的 各 部 协同 工作 的 原理 。 这 些 知 识 都 
非常 重要 ， 却 不 是 这 本 书 的 唯一 目标 。 这 本 书 还 要 讨论 如 何 构建 可 演化 的 Web API, MAS 
章 开始 ， 我 们 就 要 谈 到 如 何 创建 一 个 可 以 演化 数 年 的 Web API 一 一 这 上 段 时 间 相 当 长 ， 业 务 
关注 点 和 技术 都 会 在 此 期 间 发 生 改 变 。 


我 们 不 会 在 抽象 场景 中 讨论 如 何 构建 可 演化 的 Web API， 而 是 将 实际 动手 构造 一 个 APL， 
以 演示 需要 传达 的 概念 。 这 个 API 所 在 的 应 用 域 应 该 是 每 个 开发 者 都 熟悉 的 ， 而 且 足 够 现 
实 ， 可 以 在 真实 世界 场景 中 使 用 。 





























在 深入 这 个 应 用 域 的 细 布 之 前 ， 我 们 必须 确定 自己 真 的 做 好 准备 ， 为 获得 可 演化 性 付出 
努力 。 可 演化 性 并 不 容易 实现 。 为 了 获得 可 演化 性 ， 在 适当 的 时 候 ， 我 们 会 使 用 REST 架 
构 风 格 的 约束 。 关 键 是 要 认识 到 ， 我 们 并 不 是 要 努力 创建 一 个 “RESTful API”, REST 并 
不 是 目标 ， 而 是 实现 目标 的 手段 。 在 某 些 情况 下 ， 我 们 很 可 能 会 选择 违反 REST 的 某 些 约 
束 。 一 旦 理解 了 一 个 架构 约束 的 价值 和 需要 为 之 付出 的 代价 ， 你 就 能 够 做 出 明智 的 选择 ， 
决定 这 个 约束 是 否 与 你 的 目标 一 致 。 可 演化 性 才 是 我 们 的 目标 。 




















在 开始 设计 Web API 之 前 ， 我 们 需要 定义 应 用 域 的 组 成 部 分 。 如 今 ， 人 们 试图 构建 分 布 式 
系统 时 经 常会 忽略 这 个 定义 过 程 。 如 果 你 构建 的 是 一 个 经 典 的 基于 浏览 器 的 应 用 程序 ， 解 
决 方法 的 架构 基本 上 已 经 定义 好 了 。HTTP、HTML 页 面 、CSS 和 JavaScript 都 是 这 个 解 
决 方案 的 组 件 。 但 是 ， 如 果 要 构建 Web API， 你 就 不 再 受 限 于 Web 浏览 器 所 提供 的 选择 。 
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Web 浏览 器 可 能 只 是 这 个 分 布 式 系统 中 的 诸多 客户 端 组 件 之 一 。 


在 定义 了 应 用 域 的 组 成 部 分 之 后 ， 第 7 章 将 介绍 一 个 API 示例 ， 把 这 些 组 件 集成 为 Web 
API。 这 些 组 件 也 是 在 第 8 章 中 构建 客户 端 程序 所 需 的 关键 信息 。 通 过 定义 独立 于 API 
可 重用 的 组 件 ， 我 们 可 以 构建 这 样 的 客户 端 : 可 以 与 这 些 组 件 进行 交互 ， 而 无 需 知道 Web 
API 的 具体 类 型 。 通 过 使 用 超 媒 体 ， 客 户 端 可 以 发 现 API 的 具体 类 型 ， 并 在 API 演化 过 程 
中 适应 其 变化 。 


> w 
51 为 什么 要 可 演化 

到 底 什么 是 可 演化 的 API 呢 ? 在 一 定 程度 上 ， 演 化 只 是 变化 的 另 一 种 华丽 的 说 辞 而 已 。 但 
是 ,演化 意味 着 一 组 连续 的 微小 变化 ， 在 经 过 多 次 迭代 后 ， 最 终 的 解决 方案 可 能 会 看 起 来 
和 原来 完全 不 同 。 








在 Web API 生命 周期 中 ， 可 能 会 需要 进行 如 下 的 演化 。 


。 个 体 资源 包含 的 信息 可 能 需要 增加 或 者 减少 。 

。 单个 信息 的 表示 可 能 发 生变 化 。 名 字 或 者 数据 类 型 可 能 改变 。 
。 资源 之 间 的 关系 可 能 会 增加 或 删除 ， 或 者 关系 的 基数 发 生 改 变 。 
。 API 中 可 能 增加 全 新 的 资源 ， 用 于 表示 新 的 信息 。 

。 资源 可 能 需要 新 的 表示 ， 以 支持 不 同类 型 的 客户 端 。 

。 API 可 能 创建 新 资源 ， 提 供 更 细 粒 度 或 更 粗 粒 度 的 信息 访问 。 
。 API 支持 的 处 理 流程 可 能 发 生变 化 。 


多 年 以 来 ， 软 件 开发 行业 在 变更 管理 方面 ,一直 试图 遵循 较为 传统 的 工程 实践 。 传 统 经 验 
表明 ， 在 产品 开发 周期 的 早期 进行 变更 ， 要 比 开发 晚期 进行 变更 的 代价 小 得 多 。 常 见 的 解 
决 方案 是 进行 严格 的 变更 管理 ， 通 过 全 面 的 前 期 计划 和 设计 工作 ， 尽 量 减 少 变 更 。 近 年 
来 ， 敏 捷 软 件 开 发 实践 的 兴起 为 我 们 指出 了 另 一 种 对 待 变更 的 方式 : 把 变更 看 做 软件 开发 
过 程 的 一 部 分 。 在 小 的 迭代 中 接受 变更 ， 软 件 系 统 可 以 借 此 进行 演化 ， 以 满足 用 户 的 需 
求 。 我 们 有 时 会 看 到 网 站 在 一 天 之 内 多 次 发 布 软件 的 新 版 本 。 


但 是 ，Web API 允许 外 部 团队 开发 自己 的 软件 使 用 其 服务 ， 因 此 ， 对 于 Web API 的 变更 管 
里 ， 我 们 又 回 到 了 老 习 惯 。 我 们 的 想法 通常 是 ， 如果 修 改 API 导致 软件 不 能 运行 ， 客 户 会 不 
高 兴 ， 因 此 我 们 需要 对 API 做 出 正确 的 计划 和 设计 ， 避 免 将 来 进行 修改 。 我 们 经 常 听 说 API 
开发 者 发 布 了 2.0 版 本 的 API， 导 致 客户 端 应 用 需要 进行 许多 修订 ， 才 能 移植 到 新 版 本 。 
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SOAP 至 少 是 诚实 的 


使 用 基于 SOAP 的 解决 方案 虽然 存在 诸多 问题 ， 但 是 SOAP 解决 方案 至 少 在 变更 的 控 
制 和 管理 上 是 “诚实 ”的 。SOAP 明确 地 要 求 ， 在 API 提供 者 和 使 用 者 之 间 定 义 准确 
的 协议 ， 使 用 瀑布 式 的 集成 方式 ,做 好 前 期 工作 ， 从 而 避免 变革 。 在 今天 ,很 多 人 采 
取 与 SOAP 解决 方案 完全 不 同 的 做 法 ， 他 们 遵循 REST MBIT RAL, AP REST 风 
格 系 统 具 有 某 些 神 坷 的 属性 ， 能 够 使 变更 管理 变 得 更 容易 。 遗 憾 的 是 ， 这 些 人 只 是 把 
问题 推 后 了 而 已 。 











5.1.1 演化 的 障碍 

有 几 个 因素 会 影响 变更 处 理 的 难 易 程 度 。 最 大 的 因素 之 一 是 ， 谁 会 受到 变更 的 影响 。API 
的 使 用 者 与 开发 者 通常 是 不 同 的 困 队 。 而 且 ， 使 用 者 团队 经 常 和 开发 团队 隶属 不 同 的 公 
司 。 实 际 上 ，API 可 能 会 有 来 自 多 个 公司 的 多 个 使 用 者 。 实 施 一 个 破坏 性 的 变更 会 导致 很 
多 顾客 不 愉快 。 


即便 是 同一 个 团队 管理 使 用 者 和 生产 者 两 个 应 用 ， 也 可 能 有 约束 条 件 导 致 客户 端 和 服务 器 
无 法 同步 进行 部 署 。 如 果 客 户 端 代码 要 部 署 到 许多 客户 端 ， 就 很 难 同步 客户 端 和 服务 器 的 
更 新 ， 如 果 客 户 端 安装 在 锁定 的 机 器 上 ， 更 新 可 能 会 变 得 更 加 复杂 。 有 时， 强制 客户 端 进 
行 更 新 会 导致 糟糕 的 用 户 体验 。 如 果 用 户 想 要 使 用 一 个 客户 端 程序 ， 在 使 用 前 却 必 须 安装 
一 个 更 新 ， 用 户 也 许 会 觉得 很 扫兴 。 大 部 分 常见 的 自动 更 新 的 客户 端 软件 应 用 可 以 在 运行 
的 同时 ， 后 台 下 载 新 版 本 ， 然 后 下 一 次 重启 时 进行 更 新 。 要 使 用 这 种 更 新 方法 ， 服 务 器 软 
件 需要 能 够 至 少 在 短期 内 ， 继 续 支 持 客 户 端的 旧版 本 。 


修改 软件 的 挑战 之 一 是 ， 有 些 变更 非常 简单 ， 影 响 很 小 ， 而 有 些 变更 会 严重 影响 系统 的 很 
多 部 分 。 关 键 在 于 区 分 你 要 进行 的 是 哪 种 变更 。 在 理想 情况 下 ， 我 们 应 该 能 够 将 软件 分 
块 ， 将 改动 影响 很 小 的 部 分 与 可 能 产生 很 大 影响 的 部 分 分 开 。 举 个 简单 的 例子 ， 让 我 们 对 
LE HTML 规范 的 修改 和 在 网 站 添加 一 个 新 页 面 两 种 变更 。 修 改 HTML 规范 可 能 导致 每 个 
人 都 要 更 新 Web 浏览 器 ， 影 响 范 围 巨 大 ， 而 网 站 添加 一 个 新 页 面 则 不 会 对 Web 浏览 器 产 
生 任 何 影响 。Web 架构 的 设计 特意 做 出 了 这 种 区 分 ， 使 得 网 站 (服务器) 可 以 独立 进行 演 
化 ， 而 用 户 无 需 不 断 更 新 Web 浏览 器 (客户 端 )。 

























































































变更 需求 可 以 进行 管理 。 变 更 需求 的 管理 需要 控制 和 协调 。 我 们 能 够 采取 的 任何 辅助 长 期 
变更 的 努力 ， 都 很 容易 得 到 数 倍 的 回报 。 但 是 ， 构 建 可 演化 的 系统 并 不 容易 ， 我 们 必须 付 
出 代价 。 


5.1.2 ”代价 是 什么 


为 了 使 API 可 演化 ，REST 的 约束 不 允许 客户 端 应 用 程序 做 出 某 些 假设 。 我 们 不 允许 客 
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户 端 事先 知道 服务 器 上 可 用 的 资源 。 客 户 端 必须 在 运行 时 ， 使 用 一 个 入 口 点 URL 来 发 现 
资源 。 





客户 端 发 现 了 资源 的 URL 之 后 ， 也 不 能 对 可 能 返回 的 资源 表示 做 出 任何 假设 。 客 户 端 必 
须 使 用 响应 中 返回 的 元 数据 ， 判 断 返回 信息 的 类 型 。 








在 这 些 限 制 下 ， 相 比 传统 的 客户 端 / 服 务 器 模式 中 的 客户 端 ， 我 们 构建 的 客户 端 要 动态 得 
多 。 客 户 端 必 须 进 行 “ 功 能 检测 ”， 以 决定 哪些 功能 可 用 ， 还 必须 根据 返回 的 响应 做 出 灵 
活 处 理 。 





让 我 们 看 一 个 简单 的 例子 : 返回 一 个 订单 的 服务 器 API。 假 设 客户 端 能 够 显示 纯 文 本 、 
HTML 和 PDF 文档， 服务 器 不 需要 预先 定义 返回 何 种 格式 。 也 许 ， 在 软件 的 第 一 个 版 本 
中 ，API 返回 一 个 简单 的 纯 文 本 订单 。 服 务 器 的 新 版 本 可 能 实现 了 返回 HTML 订单 的 功 
能 。 只 要 存在 一 个 机 制 ， 客 户 端 可 以 使 用 这 个 机 制 解析 响应 ， 识 别 返 回 类 型 ， 客 户 端 就 可 
以 继续 工作 , 无 需 改变 。 这 种 包含 标识 消息 内 容 的 元 数据 的 消息 , 称 为 自 描述 性 消息 (self- 


descriptive messaging) 。 

















此 外 ,定义 API 规 范 时 应 该 说 明 必需 的 最 少 的 细节 ， 而 不 是 所 有 细节 。 爱 因 斯 坦 说 :“ 所 
有 事情 都 应 该 尽量 人 简单， 但 是 不 能 过 于 简单。 过 度 地 限定 API 会 增加 变更 ， 影 响 系统 较 
大 部 分 的 可 能 性 。 


过 度 指定 的 例子 有 : 








。 当 数 据 顺序 对 消息 语义 无 关 紧 要 时 ， 要 求 数 据 按 某 个 顺序 排列 ， 
。 当 数 据 只 在 特定 情况 需要 时 ， 认 为 数据 是 必需 的 ; 
。 限制 交互 必须 使 用 平台 定义 类 型 的 特定 序列 化 方法 。 


下 面 的 两 个 小 故事 描述 了 现实 生活 中 的 场景 ， 说 明 过 度 指定 如 何 对 结果 产生 负面 的 影响 。 






































婚礼 摄影 师 


在 这 个 真实 生活 场景 中 ， 你 会 看 到 如 何 撰写 协议 ， 以 适应 变化 。 请 比较 下 面 两 份 由 新 
娘 提 供给 婚礼 摄影 师 的 协议 条 款 。 
(1) 我 们 希望 拍摄 如 下 照片 : 

。 新 娘 在 教堂 内 外 ; 

。 HR EIRE EEE; 

。 新 郎 和 新 娘 在 教堂 门 前 的 大 橡树 穷 ; 

。 新 娘 和 伴娘 在 池塘 前 ; 

。 BBR FetE BR ALA F, 











(2) 我 们 希望 拍摄 一 些 可 以 赠 予 家 人 及 亲友 的 照片 。 我 们 也 项 望 拍 摄 其 他 更 为 私人 的 照 
片 ， 用 于 装饰 家 居 。 我 们 希望 一 些 照片 是 黑白 的 ， 以 配合 客厅 的 装饰 。 比 起 室内 照 
片 ， 我 们 更 喜欢 室外 照片 。 


第 二 份 协议 与 第 一 份 的 不 同 之 处 在 于 ， 第 一 份 描述 非常 详细 ， 但 是 没有 解释 条 款 的 意 
图 。 第 二 份 更 加 灵活 ， 同 时 也 保证 客户 的 需求 得 到 满足 。 第 二 份 协议 留 给 摄影 师 更 多 
的 创作 自由 ， 如 果 婚 礼 当 天 摄影 师 发 现 大 橡树 已 经 被 砍 挤 ， 或 者 礼 车 停 在 一 条 繁忙 的 
街道 上 ， 无 法 避 开 背景 中 的 车 辆 时 ， 摄影 师 可 以 灵活 处 理 。 











下 面 这 个 例子 中 ， 过 度 指 定 的 结果 不 是 简单 的 压抑 创造 力 和 产生 低 质量 的 产品 ， 而 是 完全 
没有 满足 原本 的 需求 。 








遗嘱 的 意图 

变化 是 不 可 避免 的 ， 如 果 今 天 做 出 过 于 精确 的 决定 ， 将 来 环境 变化 时 可 能 会 适得其反 。 
一 位 有 四 个 孩子 的 母亲 正在 准备 遗 跪 。 这 位 母亲 深 爱 她 的 每 一 个 孩子 ， 因 为 孩子 们 的 
经 济 状况 都 不 是 特别 好 ， 她 希望 在 自己 去 世 后 帮助 孩子 们 。 但 是 Johnny 沉迷 赌博 ， 母 
亲 不 想 把 钱 浪费 在 他 身上 。 母 亲 决 定 在 遗嘱 中 不 包括 Johnny， 把 钱 平均 分 给 其 他 三 
个 孩子 。 不 幸 的 是 ， 母 亲 突 发 中 风 陷 入 氏 迷 ， 几 年 之 后 终于 去 世 。 在 母亲 展 迷 的 这 
段 时 间 里 ，Johnny 不 再 赌博 ， 重 新 振作 。Billy 买 彩票 中 了 IFA, RHSRAKRB, 
Jimmy 失去 工作 ， 生 活 十 分 困难 。 母 亲 立 下 的 遗 踢 不 再 反映 她 的 本 意 。 她 本 想 尽 量 用 
金钱 帮助 自己 的 孩子 们 ， 但 是 Billy 不 再 需要 金钱 ，Johnny 却 很 需要 资金 使 生活 回 到 
正轨 。 可 惜 这 份 遗 蚁 在 钱财 如 何 分 配 上 定义 得 非常 严格 。 如 果 这 位 母亲 选择 灵活 的 措 
辞 ， 让 遗 踢 执 行人 能 够 满足 她 立定 遗嘱 的 最 初 意图 ， 结 果 本 可 以 有 很 大 的 不 同 。 











我 们 经 常 在 软件 项 目 管理 中 看 到 类 似 的 情况 : 客户 和 业务 分 析 师 试图 用 需求 来 精确 定义 他 
们 设想 的 解决 方案 ， 而 不 是 说 明 他 们 的 真实 意图 ， 让 专业 的 软件 人 员 发 挥 所 长 。 在 构建 分 
布 式 系统 时 ， 如 果 希 望 系统 能 够 长 期 运行 ， 我 们 使 用 的 协议 必须 表达 业务 伙伴 的 意图 。 















































将 运行 时 发 现 、 自 描述 性 消息 和 反应 性 客户 端 结合 在 一 起 ， 其 概念 并 不 容易 掌握 ， 也 不 易 
实施 ， 但 这 是 可 演化 系统 的 核心 组 件 ， 带 来 的 灵活 性 要 远 远 超过 实施 的 代价 。 


5.1.3 为 什么 不 创建 新 版 本 


处 理 API 中 的 破坏 性 变更 ， 传 统 的 做 法 是 使 用 版 本 的 概念 。 




















H 








从 开发 可 演化 系统 的 角度 ， 我 们 可 以 把 创建 新 版 本 当 作 最 后 一 个 办 法 ， 承 认 演 化 的 失败 。 
给 初始 API 冠 上 版 本 号 v1， 等 于 是 声明 ， 你 已 经 知道 这 个 API 无 法 演化 ， 需 要 在 v2 版 本 
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引入 破坏 性 的 变更 。 但 是 ， 有 时 我 们 的 确 会 犯错 误 ， 如 有 果 试 过 别 的 方法 都 不 成 功 ， 那 么 只 
能 选择 创建 新 版 本 。 


这 本 书 中 讨论 的 技术 ， 是 为 了 帮助 你 避免 为 API 创建 新 版 本 。 但 是 ， 如 果 确 实 需要 为 API 
的 某 些 部 分 创建 新 版 本 ， 你 可 以 试 着 缩小 演化 失败 的 范围 。 


请 不 要 误会 ， 我 们 不 是 说 你 必须 在 前 期 做 大 规模 的 设计 ， 一 开始 就 把 事情 都 做 对 。 我 们 是 
想 鼓励 一 种 极 简 化 的 态度 : 不 要 指定 不 需要 指定 的 东西 ， 不 要 创建 不 需要 的 资源 。 可 演化 
的 API 设计 就 是 为 了 适应 变化 ， 在 发 现 必须 添加 的 新 东西 时 ， 能 够 以 最 小 的 代价 完成 所 需 
的 改变 。 





版 本 变更 ， 包 括 把 一 个 标识 符 与 API 快照 或 API 的 某 部 分 联系 起 来 。 如 果 API 发 生变 化 ， 
就 需要 使 用 新 的 标识 符 。 客 户 端 和 服务 器 可 以 使 用 版 本 号 进行 协调 ， 客 户 端 用 版 本 号 判断 
是 否 能 与 服务 器 进行 通信 。 一 些 概念 (如 语义 版 本 ) 可 以 用 于 区 分 破坏 性 变更 和 非 破坏 性 
变更 。 在 可 演化 系统 内 可 以 使 用 几 种 版 本 创建 方式 ， 每 种 方式 对 系统 的 影响 程度 不 同 。 


我 们 可 以 在 如 下 位 置 进行 版 本 变更 : 





。 AB ATA (如 XML 和 HTML); 

© 有 效 载荷 类 型 (如 application/vnd.acme.foo.v2+xml) ; 
e URL 开头 (如 /v2/api/foo/bar) ; 

。 URL 结尾 (如 /api/foo/bar.v2)。 





什么 样 的 变更 是 破坏 性 的 ? 


如 果 我 们 可 以 把 API 变更 划分 为 破坏 性 和 非 破坏 性 两 种 ， 生 活 会 变 得 很 轻松 。 遗 憾 
的 是 ， 具 体 的 上 下 文 对 我 们 的 判断 有 很 大 的 影响 。 一 个 破坏 性 变更 是 会 破坏 协议 的 变 
更 ， 但 是 如 果 没 有 严格 简单 的 规定 说 明 API 协议 是 什么 ， 我 们 还 是 无 法 做 出 判断 。 在 
REST 架构 风格 中 ， 协 议 是 由 媒体 类 型 和 链接 关系 定义 的 ， 因 此 我 们 认为 ， 不 影响 媒 
体 类 型 和 链接 关系 的 变更 是 非 破坏 性 变更 ， 而 影响 这 两 种 规范 的 变更 可 能 是 破坏 性 的 ， 
也 可 能 不 是 破坏 性 的 。 











1. 基于 有 效 载荷 的 版 本 变更 

Web 架构 最 重要 的 特征 之 一 是 ，Web 将 有 效 载 答 格式 的 概念 提升 为 第 一 类 的 架构 概念 。 在 
RPC 世界 中 ， 参 数 仅仅 是 过 程 签 名 的 产物 ， 不 能 独立 使 用 。HTML 是 基于 有 效 载 位 进行 
版 本 变更 的 一 个 例子 。HTML 在 很 大 程度 上 是 一 个 自 包含 的 规范 ， 描 述 一 个 文档 的 结构 。 
HTML 规范 多 年 来 经 过 了 巨大 的 演化 。 基 于 HTML 的 Web 使 用 的 不 是 基于 URI 的 或 媒体 
类 型 的 版 本 变更 。 但 是 ，HTML 文档 的 确 包含 元 数据 ， 以 辅助 解析 器 解释 文档 的 含义 。 这 
种 版 本 变更 的 方式 可 以 限制 版 本 变更 对 媒体 类 型 解析 器 代码 的 影响 。 我 们 可 以 创建 支持 不 
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同 版 本 的 数据 传输 格式 的 解析 器 ， 更 容易 支持 旧版 本 的 文档 格式 。 但 是 要 确保 新 的 文档 格 
式 不 会 导致 日 的 解析 器 失败 ， 还 是 一 个 挑战 。 


2. 媒体 类 型 版 本 变更 

近年 来 ， 使 用 媒体 类 型 标识 符 版 本 的 做 法 日 渐 流行 。 这 种 方法 的 一 个 好 处 是 ， 用 户 代理 可 
以 使 用 Accpet 标 头 声明 自己 支持 媒体 类 型 的 哪个 版 本 。 如 果 客 户 端 处 理 得 当 ， 你 可 以 在 媒 
体 类 型 中 引入 破坏 性 变更 ， 而 现 有 客户 端 依然 可 以 工作 。 现 有 的 客户 端 会 继续 请 求 旧版 本 
的 媒体 类 型 ， 新 客户 端 可 以 使 用 新 版 本 的 媒体 类 型 。 














不 透明 标识 符 


从 HTTP 的 角度 来 看 ， 媒 体 类 型 的 版 本 变化 根本 就 算 不 上 是 真正 的 版 本 变更 ， 只 是 创 
建 了 一 个 新 的 媒体 类 型 而 已 。 对 于 HITP， 媒 体 类 型 标识 符 是 不 透明 的 字符 事 ， 不 能 从 
这 个 字符 串 中 推导 出 含义 。 因 此 ，appLication/vnd.acme.foo 和 appliction/vnd.acme. 
foo.v2 一 样 ， 都 与 text/plain 没什么 关系 。 这 些 标识 符 字 符 串 各 不 相同 ， 因 此 代表 的 
媒体 类 型 不 同 。 至 于 这 两 个 版 本 的 媒体 类 型 的 解析 代码 可 能 相似 度 达 到 99%， 不 过 是 
实现 上 的 细节 罢了 。 











使 用 媒体 类 型 创建 版 本 有 一 个 缺点 ， 这 种 做 法 加 剧 了 服务 器 被 动 协商 中 存在 的 一 个 问题 。 
一 个 服务 有 可 能 为 了 提供 各 种 内 容 而 使 用 很 多 不 同 的 媒体 类 型 。 内 容 协 商 要 求 客户 端 在 每 
个 请 求 中 都 声明 自己 能 够 显示 的 所 有 媒体 类 型 ， 给 每 个 请 求 增加 了 不 小 的 开销 。 在 媒体 
类 型 中 加 入 版 本 信息 会 使 这 个 问题 更 加 复杂 。 如 果 一 个 客户 端 支持 某 个 特定 媒体 类 型 的 
v1、v2 Fl v3 版 本 ， 那 么 ， 为 了 避免 服务 器 只 支持 旧 的 版 本 ， 我 们 需要 在 每 个 Accept 标 头 
中 都 加 入 这 三 个 版 本 吗 ? 有 些 用 户 代理 开始 采取 一 种 做 法 ， 根 据 需 要 访问 的 链接 关系 ， 在 
Accept 标 头 中 只 发 送 一 部 分 媒体 类 型 。 这 样 可 以 缩小 Accept 标 头 的 大 小 ， 但 是 用 户 代理 
必须 能 够 把 链接 关系 对 应 到 适当 的 媒体 类 型 ， 又 增加 了 额外 的 复杂 度 。 


























3. URL 版 本 变更 

URL 中 的 版 本 变更 可 能 是 在 公共 API 中 最 常见 的 做 法 。 更 准确 地 说 ， 公 共 API 经常 
在 URL 的 第 一 段 加 入 一 个 版 本 号 ， 如 http://example.org/v2/customers/34。 这 种 做 法 也 是 
REST 追随 者 批评 得 最 厉害 的 。 反 对 者 认为 ， 如 果 在 URL 中 加 入 一 个 新 的 版 本 号 ， 那 么 你 
就 隐 含 地 创建 了 一 组 带 有 新 版 本 号 的 资源 副本 ， 而 这 些 资 源 大 部 分 可 能 并 没有 发 生 改 变 。 
如 果 URL ZH CARA, AAR URL 将 会 指向 资源 的 旧版 本 ， 而 不 是 新 版 本 。 问 题 在 
于 ， 有 时 候 这 种 行为 是 我 们 希望 得 到 的 ， 而 有 时 候 不 是 。 如 果 客 户 端 有 使 用 新 版 本 资源 的 
能 力 ， 那 么 客户 端 会 希望 使 用 新 版 本 ， 而 不 是 之 前 保存 的 旧版 本 。 如 果 新 版 本 的 资源 实际 
上 和 旧版 本 一 样 ， 就 产生 了 一 个 新 问题 : 两 个 不 同 的 URL 指向 同一 个 资源 。 如 果 你 想 利 
用 HTTP 的 缓存 功能 ， 指 向 同一 资源 的 多 个 URL 会 带 来 许多 炊 端 ， 最 终 导致 缓存 中 保存 
了 同一 资源 的 多 个 副本 ,缓存 失效 操作 变 得 效率 低下 。 
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URL 版 本 变更 的 另 一 种 做 法 是 在 URL 末 尾 附近 加 入 版 本 号 ， 如 http://example.org/ 
customers/v2/34。 采 用 这 种 方法 ，API 内 的 单个 资源 可 以 独立 创建 版 本 ， 消 除了 单个 资源 
对 应 多 个 URL 的 问题 。 对 于 需要 构造 URL 的 客户 端 来 说 ， 这 种 带 版 本 信息 的 URL 构造 
起 来 比较 困难 ， 不 能 简单 地 替换 所 有 请 求 URL 的 前 段 路 径 。 超 媒体 驱动 的 客户 端 甚至 无 
法 使 用 这 种 版 本 变更 方法 ， 因 为 URI 对 超 媒 体 驱 动 的 客户 端 是 不 透明 的 ， 新 的 版 本 信息 必 
需 通 过 带 版 本 的 链接 关系 来 获得 。 











API 的 版 本 变更 非常 困难 ， 很 容易 出 错 。 我 们 还 是 应 该 尽 一 切 可 能 避免 进行 版 本 变更 ， 这 
种 努力 会 带 来 很 多 长 期 的 益处 。 


5.1.4” 付 诸 实 践 

本 章 到 现在 为 止 ， 我 们 已 经 大 致 讨论 了 开发 可 演化 应 用 程序 的 利 次 。 在 开发 可 演化 的 分 布 
式 应 用 过 程 中 ， 很 多 时 候 你 需要 做 出 选择 ， 而 正确 的 答案 经 常 是 :“ 视 情况 而 定 。 我 们 不 
可 能 在 有 限 的 篇 幅 内 ， 讨 论 每 一 种 可 能 性 和 每 一 种 结果 。 但 是 ， 展 示 对 于 某 些 情况 做 出 的 
某 些 选择 ， 还 是 有 价值 的 。 在 本 章 余下 的 部 分 ， 我 们 将 关注 一 个 具体 的 应 用 程序 ， 这 个 应 
用 具有 和 常见 的 问题 ， 我 们 将 讨论 各 种 选择 ， 做 出 决定 。 我 们 在 随后 的 章节 中 ， 为 每 种 情况 
做 出 的 选择 未 必 最 佳 ， 但 是 这 些 选 择 可 以 作为 示例 ， 告 诉 你 在 构建 可 演化 API 时 将 面 对 的 
各 种 选择 和 需要 做 出 的 决定 。 


5.2 应 用 程序 目标 


为 演示 用 的 应 用 程序 示例 挑选 应 用 域 总 是 特别 困难 。 这 个 域 应 该 是 真实 的 ， 但 是 不 能 纠缠 
于 过 多 的 专业 细 市 ， 这 个 域 应 该 足够 复杂 ， 可 以 提供 各 种 场景 ， 但 是 不 能 过 大 ， 以 免 架构 
原则 淹没 在 实现 细 市 中 。 为 了 免除 你 学 习 专 业 领 域 知 识 的 麻烦 ， 我 们 选择 了 一 个 软件 开发 
者 都 很 熟悉 的 应 用 域 : 问题 跟踪 。 我 们 都 见 过 各 种 问题 跟踪 系统 的 实现 ， 既 有 客户 端的 ， 
也 有 服务 器 的 。 问 题 跟踪 系统 主要 关注 的 是 不 同 团 队 成 员 之 间 的 沟通 和 信息 共享 ， 因 此 很 
自然 地 是 分 布 式 的 。 问 题 的 生命 周期 有 很 多 的 用 例 。 问 题 有 很 多 不 同 的 类 型 ， 各 有 不 同 的 
状态 集 。 问 题 有 很 多 相关 的 各 种 元 数据 。 







































































5.2.1 目标 
对 于 认定 属于 问题 跟踪 应 用 域 的 信息 ， 我 们 要 为 其 定义 类 型 。 我 们 希望 能 够 : 





。 定义 表示 一 个 问题 所 需 的 最 小 的 一 组 信息 ， 
。 定义 通常 与 问题 相关 的 一 组 核心 信息 ， 

。 确定 系统 中 信息 之 间 的 关系 ; 

。 定义 问题 的 生命 周期 ， 

。 定义 与 问题 相关 的 行为 ; 
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。 对 于 可 以 在 问题 上 执行 的 聚合 、 过 滤 和 统计 类 型 进行 分 类 。 


我 们 并 不 会 试图 完备 地 定义 最 终 的 ， 无 所 不 包 的 问题 结构 。 我 们 的 目标 不 是 定义 问题 跟踪 
的 应 用 域 中 每 个 可 能 场景 的 功能 ， 而 是 要 定义 一 组 通用 的 信息 和 术语 ， 用 于 把 信息 传达 给 
希望 构建 某 种 问题 跟踪 应 用 程序 的 人 ， 而 不 局 限于 这 些 应 用 程序 的 范围 。 我 们 定义 的 内 容 
将 会 发 生 演化 。 


如 有 果 你 对 试图 解决 同一 领域 问题 的 不 同 应 用 程序 进行 比较 ， 经 常会 发 现 这 些 应 用 解决 同一 
问题 的 方式 略 有 不 同 。 我 们 要 确定 什么 情况 下 不 同 的 选择 是 无 关 紧 要 的 ， 直 接 挑 选 一 个 ， 
或 者 两 个 选项 都 启用 。 当 我 们 最 终 把 这 个 域 提 炼 成 媒体 类 型 规范 、 链 接 关 系 和 语义 档案 
时 ， 就 应 该 得 到 一 个 通用 的 基础 ， 既 提供 一 定 程度 的 交互 性 ， 又 不 必 局 限 单个 应 用 程序 于 
提供 单一 功能 



































5.2.2 机 会 

问题 跟踪 应 用 域 是 时 候 需 要 改进 了 。 问 题 跟 踪 有 不 少 商业 应 用 和 开源 的 应 用 ， 但 是 这 些 应 
用 都 使 用 专用 格式 进行 服务 器 和 客户 端 组 件 间 的 交互 。 问 题 数 据 锁 定 在 专用 数据 存储 库 
中 ， 而 这 些 数据 存储 库 与 创建 这 些 数据 的 应 用 紧密 相关 。 要 访问 一 个 特定 的 问题 数据 存储 
库 ， 我 们 只 能 使 用 专 为 这 个 存储 库 设 计 的 客户 端 工具 。 为 什么 我 不 能 使 用 我 选择 的 问题 管 
理 客户 端 ， 同 时 管理 在 Bitbucket 和 GitHub 存储 库 中 的 工作 事项 呢 ? 为 什么 要 有 多 个 存储 
库 呢 ? 从 来 没有 人 想 编 写 专 门 用 于 Apache 或 IIS 的 Web 浏览 器 ， 那 么 在 其 他 使 用 分 布 式 
数据 的 应 用 领域 ， 为 什么 我 们 要 坚持 把 客户 端 和 服务 器 应 用 捆绑 在 一 起 ? 


遗憾 的 是 ， 通 过 重用 标准 媒体 类 型 ， 进 行 Web 架构 的 重 构 和 重用 ,似乎 并 不 符合 商业 组 织 
的 利益 。 通常 ， 只 有 在 开源 项 目 推动 事情 发 展 之 后 ， 商 业 组 织 会 注意 并 且 认识 到 ， 集 成 
和 互 操作 性 实际 上 也 会 给 商业 软件 带 来 巨大 的 好 处 。 


5. 3 信 息 模 型 


在 开始 定义 媒体 类 型 、 链 接 关系 或 语义 档案 之 前 ， 我 们 必须 对 在 Web 上 进行 通信 所 需 的 语 
义 有 一 个 更 为 清晰 的 理解 。 

在 根本 上 ， 用 一 个 简短 的 字符 囊 文本 就 可 以 描述 一 个 问题 ， 例 如 、 在 屏幕 了 点 击 按钮 工时 
应 用 程序 会 失败 ”。 此 外 ， 人 们 通常 希望 问题 定义 包含 更 详细 的 描述 。 
























































请 看 下 面 这 个 极为 简单 的 问题 定义 : 











Issue 
Title 
Description (Optional) 
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如 果 有 人 要 了 解 并 解决 这 个 问题 ， 这 个 定义 可 能 就 足够 了 。 虽 然 这 个 问题 没有 包含 创建 者 
和 创建 时 间 信 息 ， 但 是 这 些 信息 可 以 在 发 出 创建 这 个 问题 的 请 求 时 ， 从 可 用 的 环境 信息 中 
获取 。 这 个 极 简 的 问题 表示 可 以 作为 一 个 容易 实现 的 起 点 ， 之 后 再 进行 演化 。 使 用 这 种 最 
简单 的 定义 ， 我 们 可 以 很 快 构建 出 能 够 运行 的 程序 ， 进 行 演 示 ， 而 且 也 可 用 于 比较 简易 的 
客户 端 ， 如 电话 。 人 们 可 以 在 问题 创建 之 后 ， 使 用 功能 更 强 的 客户 端 添 加 更 多 的 信息 。 











5.3.1 Fit 

在 匆忙 开始 实现 这 个 极 简 的 表示 之 前 ， 我 们 还 需要 更 好 地 了 解 可 能 与 问题 相关 的 各 种 数 
据 。 为 了 更 好 地 组 织 内 容 ， 我 把 这 些 信 息 分 为 四 个 子 域 : 描述 信息 、 分 类 信息 、 状 态 信息 
和 历史 信息 。 


1. 描述 信息 

描述 信息 子 域 包 括 我 们 已 经 讨论 过 的 信息 〈 如 标题 和 描述 ) ， 还 有 环境 信息 ， 如 软件 版 本 、 
主机 操作 系统 、 硬 件 配置 、 重 现 步 又 以 及 屏幕 截图 。 任 何 与 问题 产生 环境 相关 的 详细 信息 
都 可 以 归 在 这 个 子 域 。 描 述 信息 的 一 个 重要 特征 在 于 ， 它 主要 只 是 供 人 工读 取 的 。 描 述 信 
息 不 会 影响 问题 的 工作 流 或 者 对 任何 算法 产生 影响 。 


2. 分 类 信息 
分 类 信息 主要 用 于 将 问题 进行 有 意义 的 分 组 。 问 题 可 以 带 有 一 些 属 性 ， 这 些 属 性 值 的 范围 
预先 已 经 定义 ， 用 于 问题 的 分 类 处 理 ， 例 如 : 优先 级 、 严 重 性 、 软 件 模块 、 应 用 领域 以 及 
避 题 类 型 缺陷、 功能 等 )。 分 类 信息 用 于 问题 的 搜索 、 过 滤 和 分 组 ， 经 常用 于 决定 应 用 
程序 的 工作 流 。 通 常 ， 分 类 信息 在 问题 生命 周期 的 早期 指定 ， 除 非 信息 指定 错误 ， 否 则 不 
会 发 生 改 变 。 






































3. 状态 信息 

问题 通常 有 一 组 属性 ， 用 于 定义 当前 状态 ， 例 如 : 当前 工作 流 状 态 、 问 题 的 所 有 者 、 剩 余 
时 间 和 完成 进度 。 在 问题 的 生命 周期 中 ， 状 态 信 息 会 多 次 改变 。 状 态 信息 也 可 以 用 做 分 类 
属性 。 问 题 的 当前 状态 也 可 能 带 有 文本 注释 。 
4. 历史 信息 


历史 信息 通常 记录 之 前 某 个 时 间 点 问题 的 状态 。 历 史 信息 一 般 对 问题 的 处 理 并 不 重要 ， 但 
是 可 以 用 于 分 析 过 去 的 问题 ， 或 者 调查 某 个 问题 的 历史 记录 。 











5.3.2 ”相关 资源 

我 们 前 面 提 到 的 所 有 信息 ， 都 可 以 用 两 种 方式 之 一 表示 一 一 本 地 数据 类 型 的 简单 序列 化 
(如 字符 串 、 日 期 和 布尔 值 ) ， 或 者 代表 另 一 个 资源 的 标识 符 。 例 如 : 要 标识 相关 的 人 员 ， 
我 们 可 能 使 用 IssueFoundBy 和 IssueResolvedby, 











88 | 第 5 章 


我 们 可 以 简单 地 使 用 一 个 字符 串 标识 相关 人 员 ， 但 是 使 用 资源 标识 符 要 有 价值 得 多 ， 因 为 
问题 跟踪 系统 的 用 户 很 可 能 会 定义 为 资源 。 资 源 标识 符 自然 会 使 用 URL。 如 果 使 用 URL， 
客户 端 软件 就 有 机 会 对 URL 进行 非 关联 化 ， 获 得 相关 人 员 的 更 多 信息 。 问 题 属性 和 人 员 
属性 中 的 信息 有 着 极为 不 同 的 生存 期 ， 因 此 适合 使 用 不 同 的 资源 。 数 据 的 持久 性 不 同 ， 就 
可 能 使 用 不 同 的 缓存 策略 。 



































在 人 们 浏览 问题 时 ， 我 们 可 能 不 想 在 其 面前 展示 URL。 要 解决 这 个 问题 ， 我 们 可 以 使 用 链 
接 。 通 常 ， 我 们 不 会 在 表示 中 直接 伐 入 URL， 因 为 这 个 URL 经 常 有 相关 的 其 他 元 数据 。 
Link 是 一 个 带 有 相关 元 数据 的 URL， 其 中 一 个 标准 元 数据 是 Title 属性 。Titte 属性 提供 
URL 的 一 个 人 工读 取 的 版 本 。 使 用 链接 ， 我 们 可 以 获得 两 方面 的 好 处 : 一 个 戏 入 的 、 可 人 
工读 取 的 描述 ， 以 及 一 个 URL， 指 向 包含 了 相关 人 员 的 附加 信息 的 唯一 资源 。 

















下 面 是 一 个 相关 资源 的 示例 : 


<resource> 
<Title>App blows up</Title> 
<Description>Pressing three buttons at once causes crash</Description> 
<links> 
<Link rel="IssueFoundBy" 
title="Found by" 
href="http://example.org/api/user/bob"/> 
</links> 
</resource> 


5.3.3 ”属性 组 


有 时 我 们 需要 把 属性 组 织 在 一 起 ， 使 表示 更 容易 理解 。 当 一 组 属性 需要 作为 一 个 整体 处 理 
时 ， 使 用 属性 组 可 以 简化 客户 端 代 码 。 如 果 用 户 代理 不 想 处 理 相关 的 属性 ， 我 们 就 可 以 忽 
略 整个 属性 组 。 我 们 还 可 以 使 用 属性 组 引入 对 强制 信息 的 条 件 需求 。 例 如 ， 如 果 使 用 组 马 ， 
就 必须 在 组 中 包含 属性 Y。 使 用 这 种 方法 ， 我 们 可 以 支持 一 个 最 简 的 表示 ， 同 时 还 能 确保 ， 
如 果 表 示 包 含 问题 的 某 个 方面 信息 ， 那 么 必须 提供 关键 信息 。 举 一 个 具体 的 例子 ， 如 有 果 你 
要 提供 一 个 问题 在 过 去 某 个 时 间 的 历史 记录 ， 就 必须 提供 日 期 和 时 间 属 性 。 

























































































但 是 ， 定 义 属性 组 并 在 媒体 类 型 中 使 用 这 些 组 ， 会 带 来 一 个 风险 。 如 果 你 发 现 一 个 属性 分 
组 错误 ， 要 将 它 移动 到 一 个 新 的 组 ， 可 能 会 导致 破坏 性 的 变更 。 因 此 在 使 用 属性 组 时 必须 
非常 谨慎 。 


下 面 是 一 个 属性 组 的 示例 : 




















<resource> 
<Title>App blows up</Title> 
<Environment> 
<OperatingSystem>Windows ME</OperatingSystem> 
<AvailLableRAM>284MB</AvaiLablLeRAM> 
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<AvailableDiskSpace>1.2GB</AvailableDiskSpace> 
</Environment> 
</resource> 


5.3.4 属性 组 的 集合 

当 你 要 在 一 个 表示 内 表示 多 个 同类 的 属性 时 ， 可 以 使 用 属性 组 集合 。 问 题 可 能 带 有 附加 文 
档 。 这 些 文档 很 可 能 会 表示 为 链接 ， 但 是 这 些 文档 可 能 还 有 附加 的 属性 ， 这 些 属 性 可 以 放 
在 一 个 属性 组 里 。 采 用 这 种 做 法 ， 这 些 文档 的 多 个 属性 组 可 以 包含 在 一 个 资源 表示 内 ， 同 
时 还 可 以 维护 文档 及 其 相关 属性 的 关系 。 





























下 面 是 一 个 属性 组 集合 的 示例 : 








<resource> 
<Title>App blows up</Title> 
<Documents> 
<Document> 
<Name>ScreenShot. jpg</Name> 
<LastUpdated>2013-11-03 10:15AM</LastUpdated> 
<Location>/documentrepository/123233</Location> 
</Document> 
<Document> 
<Name>StepsToReproduce. txt</Name> 
<LastUpdated>2013-11-03 10:22AM</LastUpdated> 
<Location>/documentrepository/123234</Location> 
</Document> 
</Documents> 
</resource> 


5.3.5 ”信息 模型 与 媒体 类 型 

到 这 里 ， 我 们 已 经 介绍 了 问题 跟踪 应 用 域 的 信息 模型 。 我 们 还 抽象 地 讨论 了 这 些 不 同 的 信 
息 如 何 表示 、 组 织 和 关联 (参见 图 5-1)。 我 避 开 了 对 具体 格式 (如 XML 和 JSON) Wit 
因为 信息 模型 的 定义 是 独立 于 具体 的 表示 语法 的 ， 理 解 这 一 点 非常 重要 。 至 于 如 何 把 
模型 具体 映射 到 实际 媒体 类 型 的 语法 及 其 特定 格式 ， 在 下 一 章 讨 论 媒体 类 型 时 ， 我 们 


A 
将 会 解决 这 个 问题 。 


关于 这 个 信息 模型 的 可 重用 性 ,我们 需要 考虑 儿 件 事情 。 虽 然 这 个 模型 列 出 的 功能 不 少 ， 
但 大 部 分 都 是 可 选 的 ， 因 此 我 们 可 以 在 最 简单 和 最 复杂 的 场景 都 使 用 同一 个 模型 。 但 是 ， 
为 了 实现 互 操作 性 ， 我 们 必须 进行 明确 的 定义 ， 给 出 具体 的 属性 名 。 幸 运 的 是 ， 我 们 定义 
的 只 是 一 个 接口 规范 。 应 用 程序 在 存储 数据 时 ， 并 不 需要 使 用 我 们 定义 的 属性 名 ， 只 要 能 
够 向 用 户 准确 传达 数据 的 语义 就 可 以 。 











= S 





































可 用 磁盘 空间 





作者 














图 5-1: 信息 模型 


在 定义 媒体 类 型 时 ， 我 们 必须 考虑 ， 如 果 一 个 应 用 程序 要 包含 我 们 当前 的 信息 模型 不 支持 
的 语义 时 ， 该 如 何 处 理 。 可 扩展 性 是 一 项 重要 的 目标 ， 但 是 ， 构 建 可 以 互 操作 的 可 扩展 性 
已 经 超出 了 我 们 讨论 的 范围 ， 因 此 这 个 信息 模型 中 对 此 不 做 支持 。 当 然 ， 我 们 并 不 反对 媒 
体 类 型 定义 自己 的 可 扩展 性 选项 ， 让 特殊 的 客户 端 和 服务 器 处 理 扩展 数据 。 












































5.3.6 ”问题 集合 
除了 单个 问题 的 表示 ， 我 们 的 应 用 程序 可 能 还 需要 能 够 表示 一 组 问题 。 问 题 集合 的 表示 最 
有 可 能 在 一 些 查询 请 求 返回 的 结果 中 用 到 。 在 下 一 章 ， 我 们 将 介绍 两 种 方法 ， 一 种 是 构建 
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新 的 媒体 类 型 用 于 问题 集合 的 表示 ， 另 一 种 是 重用 现 有 媒体 类 型 的 列表 功能 ， 并 讨论 二 者 
各 自 的 优点 ， 同 时 还 会 介绍 现存 的 各 种 “混合 ”做 法 。 


5.4 资源 模型 


构建 Web API 时 ， 应 用 架构 中 需要 考虑 的 另 一 个 主要 方面 是 公布 的 资源 。 我 并 不 想 预 先 定 
义 好 问题 跟踪 API 必须 使 用 的 资源 。 可 演化 的 API 和 RPC/SOAP API 最 主要 的 区 别 之 一 就 
是 ， 可 演化 的 API 的 接口 定义 不 包括 可 用 的 资源 。 我 们 预期 由 客户 端 发 现 资源 ， 客 户 端 的 
功能 受 限于 它 能 发 现 的 资源 。 














我 想 要 讨论 的 是 API 必须 公布 的 资源 类 型 ， 以 帮助 我 们 探索 客户 端 需要 支持 的 媒体 类 型 。 
从 最 小 的 一 组 资源 开始 总 是 没 错 的 。 系 统 中 的 资源 应 该 能 够 容易 、 快 速 地 创建 ， 在 我 们 获 
得 了 用 户 使 用 服务 的 真实 经 验 后 ， 就 可 以 很 容易 地 添加 新 的 资源 ， 以 满足 更 多 的 需求 。 





5.4.1 根 资源 

每 个 可 演化 的 Web API 都 需要 一 个 根 资源 (root resource)。 没 有 根 资源 ， 客 户 端 就 无 法 开 
始 发 现 资源 的 过 程 。 根 资源 的 URL 是 唯一 不 能 改动 的 。 这 个 资源 主要 会 包括 指向 应 用 程 
序 内 其 他 资源 的 一 组 链接 。 这 些 链接 有 些 可 能 指向 搜索 资源 。 





5.4.2 RAR 

搜索 资源 (search resource) 的 一 个 典型 例子 是 一 个 HTML 表单 ， 表 单 上 有 一 个 输入 框 
使 用 输入 的 值 作 为 查询 字符 串 进 行 GET 请 求 。 搜 索 资源 有 可 能 比 这 个 例子 复杂 得 多 ， 有 时 
能 够 完全 用 URI 模板 替代 。 搜 索 资 源 通 常会 包含 一 个 链接 ， 返 回 某 些 资源 集合 。 











5.4.3 ”集合 资源 

集合 资源 (collection reosource) 返回 的 表示 通常 包含 一 列 属性 组 ， 每 个 属性 组 经 常会 包含 
一 个 链接 ， 这 个 链接 指向 属性 组 中 信息 代表 的 那个 资源 。 

一 个 问题 跟踪 应 用 程序 有 可 能 会 预先 定义 很 多 集合 资源 ， 例 如 : 

。 未 解决 问题 ， 

。 已 关闭 问题 ， 

。 用 户 列表 ， 

e 项 目 列表 。 








通常 ，Web API 可 以 使 用 搜索 参数 ， 生 成 筛选 结果 集合 ， 以 此 定义 大 部 分 的 集合 资源 。 使 
用 资源 这 个 词 时 ， 我 们 要 理解 资源 这 个 概念 和 生成 资源 表示 的 底层 实现 之 间 的 区 别 ， 这 
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一 点 很 重要 。 如 果 我 创建 一 个 IssueController， 为 客户 端 应 用 搜索 问题 子 集 ， 那 么 / 
issues?foundBy='Bob' 和 /issues?foundBy='Bill' 这 两 个 URL 是 两 个 不 同 的 资源 ， 虽 然 生 成 
这 两 个 资源 的 代码 可 能 是 完全 一 样 的 。 这 两 个 资源 是 同一 概念 的 不 同 实例 ， 就 我 所 知 ， 没 
有 一 个 常用 的 词 可 以 描述 这 种 资源 的 共同 特征 。 从 这 里 开始 ， 我 会 使 用 资源 类 (resource 
class) 来 指 代 这 种 情况 。 


5.4.4 个 体 资源 
通过 问题 跟踪 Web API 获取 的 大 部 分 信息 都 可 以 通过 个 体 资 源 (item resource) 来 传递 。 
个 体 资 源 提供 一 个 表示 ， 包 含 信息 模型 中 某 个 概念 的 单个 实例 的 一 些 或 全 部 信息 。 我 们 可 
能 需要 支持 不 同 详细 程度 的 表示 。 例 如 : 一 些 客户 端 可 能 只 需要 问题 的 描述 性 属性 ， 而 其 
他 客户 端 可 能 需要 问题 的 所 有 可 编辑 属 ' 

















客户 端 在 特定 的 情况 下 需要 的 信息 子 集 可 能 会 各 不 相同 。 因 此 在 任何 issue 相关 的 媒体 类 
型 定义 中 ， 对 于 包含 或 不 包含 哪些 信息 ， 我 们 的 定义 是 非常 灵活 的 。 一 个 问题 资源 的 表示 
不 包含 历史 信息 并 不 意味 着 这 些 历史 信息 不 存在 。 如 果 我 们 基于 域 对 象 的 序列 化 来 生成 资 
源 的 表示 ， 就 无 法 解决 这 个 问题 。 一 个 对 象 只 有 一 个 类 定义 ， 因 此 无 法 根据 上 下 文 来 选择 
序列 化 这 个 对 象 哪些 部 分 。 























在 考虑 资源 中 应 该 包含 哪些 属性 时 ， 我 们 重点 需要 考虑 儿 个 因素 。 使 用 大 而 全 的 资源 表 
示 ， 可 以 减少 来 回 交 互 的 次 数 。 但 是 ， 在 只 需要 少量 数据 时 ， 使 用 大 的 资源 表示 就 会 浪费 
带宽 和 处 理 时 间 。 另 外 ， 大 的 资源 表示 更 有 可 能 包含 不 同 水 平 的 易 变性 。 如 有 果 在 一 个 资源 
中 既 包 含 描述 性 属性 ， 又 包含 状态 属性 ， 由 于 状态 信息 经 常 发 生 改变 ， 我 们 无 法 随心 所 欲 
地 长 时 间 缓存 资源 表示 。 一 个 实用 的 技巧 是 ， 参 照 数据 的 易 变 性 ， 把 数据 组 织 在 不 同 的 资 
源 中 。 把 一 个 概念 分 成 多 个 资源 的 缺点 是 ， 使 用 PUT 方法 进行 原子 更 新 操作 会 更 加 困难 ， 
而 且 会 使 缓存 失效 机 制 变 得 更 为 复杂 。 


使 用 更 多 更 小 的 资源 ， 意 味 着 我 们 要 管理 更 多 的 链接 和 表示 ， 但 是 也 意味 着 有 更 多 重用 的 
机 会 。 























要 决定 资源 定义 的 最 佳 粒度 ， 没 有 公式 化 的 方法 可 用 。 关 键 是 要 考虑 具体 的 使 用 场景 ， 以 
及 我 们 刚才 讨论 的 各 种 因素 ， 选 择 对 具体 场景 最 合适 的 资源 大 小 。 

图 5-2 展示 了 一 个 可 能 用 于 问题 跟踪 服务 的 资源 模型 。 服 务 会 把 每 个 资源 或 资源 类 发 布 在 
一 个 特定 的 URL。 我 们 没有 展示 具体 的 URL， 因 为 这 些 URL 与 设计 无 关 ， 和 客户 端 也 没 
有 关系 。 
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Closedlssues 


- ClosedByName: 
- ClosedSinceDate: 
- ClosedBeforeDate: 





AuthenticatedUser 


















5-2: 资源 模型 


很 多 时 候 ， 开 发 者 在 构建 API 时 会 试图 “ 按 URL ixit” (design by URL)。 但 使 用 这 种 方 
法 有 若干 问题 。 按 URL 设计 会 使 人 们 把 应 用 程序 定义 成 层级 的 数据 结构 ， 而 不 是 应 该 建 





模 的 应 月 


会 进而 约束 系统 的 设计 。 按 URL 设计 还 会 鼓励 开发 者 在 凶 

















程序 工作 六 /状态 机 。 所 选 实 现 框架 在 解析 、 处 到 


E 和 分 发 URL 能 力 上 受到 限制 ， 














È URL 结构 时 保持 一 致 性 ， 而 


这 种 一 致 性 完全 没有 必要 ， 还 可 能 给 设计 造成 约束 。 资 源 以 及 资源 间 关 系 的 标识 可 以 完全 
独立 于 URI 的 结构 ， 设 计 完 成 后 再 把 URI 空间 映射 到 资源 空间 ， 这 是 使 用 超 媒体 驱动 客 
户 端的 系统 的 独特 优点 。 如 果 客 户 端 基 于 服务 器 URI 空间 来 构造 URI， 那 么 设计 者 就 会 倾 
向 于 使 用 具有 明显 结构 的 统一 的 URI 空间 。 








94 | 第 5 章 


只 要 客户 端 能 够 理解 我 们 在 下 一 章 中 将 讨论 的 媒体 类 型 和 链接 关系 ， 就 可 以 使 用 这 个 问题 
跟踪 服务 ， 无 需 事先 了 解 根 资 源 以 外 的 任何 资源 。 


5.5 ZF 


本 章 关注 的 是 问题 跟踪 应 用 程序 的 概念 设计 。 我 们 回顾 了 构建 可 演化 系统 的 初衷 和 需要 付 
出 的 努力 ， 定 义 了 设计 的 组 成 部 分 ， 并 对 相关 的 应 用 领域 进行 了 总 结 。 
在 根本 上 ， 我 们 要 实现 的 是 一 个 在 不 同系 统 间 进行 通信 的 分 布 式 应 用 。 为 了 使 这 个 实现 能 


够 成 功 地 进行 演化 ， 我 们 需要 定义 在 系统 组 件 之 间 传 递 应 用 语义 的 规范 。 这 是 下 一 章 讨 论 
的 重点 。 
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第 6 章 


媒体 类 型 选择 与 设计 





订 好 协议 ， 友 谊 常 青 。 








我 们 党 第 昕 到 开发 人 员 说 ， 基 于 REST 的 系统 比 别 的 Web API 构建 方法 更 好 ， 是 因为 基于 
REST 的 系统 更 简单 。 人 们 经 常 认为 ， 不 使 用 协议 是 为 了 使 系统 简单 ， 例 如 ,WSDL (Web 
Service Description Language，Web 服务 描述 语言 ) 就 是 如 此 。 














但 是 ， 在 构建 分 布 式 系统 时 ， 不 可 避免 地 要 在 组 件 之 间 预 先进 行 一 些 约定 。 如 果 没 有 某 种 
形式 的 共享 知识 ， 组 件 间 就 无 法 进行 有 意义 的 交互 。 


本 章 将 介绍 Web 架构 中 使 用 的 协议 类 型 ， 如 何 选择 符合 我 们 需求 的 最 佳 协 议 ， 以 及 什么 地 
方 需要 创建 新 的 协议 。 


6.1 自 描 述 


设计 协议 的 一 个 关键 概念 是 自 描述 。 理 想 情 况 下 ， 一 个 消息 应 该 包含 所 有 必要 的 信息 ， 供 
消息 接收 者 理解 发 送 者 的 意图 ， 或者， 至 少 能 提供 所 需 信息 的 参考 位 置 。 


假设 你 收 到 一 封 信 ， 信 上 写 着 “43.03384, -71.07338”。 这 封 信 提 供 了 为 完成 某 项 具体 目标 
所 需 的 全 部 数据 ， 但 是 你 缺少 实际 应 用 这 些 数据 所 需要 的 上 下 文 ， 从 而 无 法 使 用 。 如 果 我 
告诉 你 ， 这 一 组 数字 是 经 纬度 ， 那 么 你 应 该 能 理解 这 些 数字 的 含义 。 显 然 ， 我 假设 你 要 么 
已 经 理解 坐标 系 的 概念 ， 要 么 能 够 自己 搜索 到 如 何 使 用 坐标 系 的 信息 。 自 描述 并 不 是 说 消 
息 需 要 真 的 包含 经 纬 坐标 系 的 描述 ， 而 只 是 需要 用 某 种 方式 引用 这 个 概念 。 

















知道 信 中 的 信息 是 坐标 ， 任 务 只 完成 了 一 半 。 应 该 怎么 使 用 这 些 坐 标 呢 ? 你 还 需要 更 多 的 
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相关 信息 。 如 有 果 你 看 到 这 封 信 的 回 邮 地 址 写 着 “内 华 达 州 ， 畅 饮 好 去 处 ， 邮 政信 箱 2000 ， 
那么 可 能 猜想 到 ， 这 组 坐标 也 许 是 一 个 推荐 酒吧 的 地 址 。 


6.2 协议 类 开 
在 Web 的 世界 里 ,媒体 类 型 用 来 表达 一 个 资源 表示 什么 ， 链 接 关 系 说 明 你 为 什么 应 对 这 个 
资源 感 兴 趣 。 媒 体 类 型 和 链接 关系 ， 就 是 我 们 在 构建 可 演化 系统 时 使 用 的 协议 。Web 架构 
中 的 媒体 类 型 和 链接 关系 代表 着 共享 知识 。 在 设计 系统 时 ， 我 们 必须 精心 设计 媒体 类 型 和 
链接 关系 ， 如 果 媒 体 类 型 和 链接 关系 发 生 改变 ， 就 会 破坏 依赖 它们 的 组 件 。 


6.3 ”媒体 类 型 


媒体 类 型 是 独立 于 平台 的 类 型 ， 设 计 用 于 分 布 式 系统 间 的 通信 。 媒 体 类 型 用 于 传递 信息 ， 
一 个 正式 的 规范 定义 了 这 些 信息 应 该 如 何 表示 。 


it PEAY AE, Web API 远 远 没 有 发 挥 媒 体 类 型 的 潜力 。 绝 大 多 数 的 Web API 只 支持 
application/xml 和 application/json。 这 两 个 媒体 类 型 传递 语义 的 能 力 极 为 有 限 ， 导 致 
人 们 经 常 使 用 离线 (out-of-band) 知识 来 解释 信息 的 内 容 。 离 线 知识 与 自 描述 信息 正好 
相反 。 回 到 我 们 刚才 那个 信件 的 例子 ， 如 果 在 你 收 到 信之 前 , “畅饮 好 去 处 ”公司 已 经 告 
诉 你 ， 信 上 的 数字 会 是 地 理 坐 标 ， 那 么 我 们 就 认为 这 个 信息 是 离线 知识 。 解 释 数据 所 需 
的 信息 是 通过 消息 自身 之 外 的 手段 传递 的 。 如 果 使 用 通用 类 型 ， 如 application/xml 和 
application/json， 我 们 就 需要 用 别 的 方法 来 传达 消息 的 语义 。 如 果 处 理 得 不 好 ， 系 统 的 
演化 就 会 变 得 更 加 困难 ， 因 为 我 们 需要 以 离线 方式 传递 系统 发 生 的 变化 。 使 用 离线 知识 
时 ， 客 户 端 推测 服务 器 将 发 送 某 种 内 容 ， 如 果 服 务 器 返回 的 内 容 改 变 ， 客 户 端 就 会 无 法 自 
动 适应 这 种 变化 。 结 果 就 是 ， 客 户 端的 存在 锁定 了 服务 器 的 行为 。 使 用 离线 知识 可 能 成 为 
阻止 系统 演化 的 主要 原因 之 一 。 


6.3.1 原始 格式 
这 一 节 将 给 出 几 个 示例 ， 演 示 如 何 通过 不 同 的 媒体 类 型 传递 同一 组 数据 。 


示例 6-1 中 展示 的 媒体 类 型 application/octet-stream， 大概 是 你 能 使 用 的 最 基本 的 媒体 
类 型 。 这 个 媒体 类 型 是 简单 的 字 节 流 。 接 收 到 这 个 媒体 类 型 ， 用 户 代理 通常 只 是 让 用 户 把 
字 市 保存 在 文件 中 ， 别 的 什么 也 不 能 做 。 这 个 媒体 类 型 没有 定义 任何 应 用 程序 语义 。 








































































































示例 6-1: 字 节 流 
GET /some-mystery-resource 
200 OK 
Content-Type: application/octet-stream 
Content-Length: 20 


00 3b 00 00 00 Od 00 01 OO 11 00 1e OO 08 01 6d 00 03 FF FF 
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示例 6-2 中 展示 的 媒体 类 型 IRRE aia 告诉 我 们 ， 消 息 内 容 可 以 稳妥 地 直接 展示 给 最 终 用 
户 ， 使 用 户 能 够 读 到 这 些 数据 。 这 个 示例 中 的 正文 没有 给 出 任何 提示 数据 用 途 的 信息 。 但 
是 服务 器 完全 可 以 在 正文 中 加 入 一 oe 说 明 信 息 的 用 途 


示例 6-2: 人 工 可 读 
GET /some-mystery-resource 
200 OK 
Content-Type: text/plain 
Content-Length: 29 


59,0,13,1,17,30,8,365,3,65535 





谁 了 解 我 的 业务 ? 


过 去 50 年 间 ， 业 务 应 用 程序 的 语义 在 系统 的 各 处 来 回 使 用 。 在 大 型 机 时 代 ， 服 务 器 了 
解数 据 的 一 切 信 息 ， 客 户 汝 只 是 显示 字符 和 检测 按键 的 终端 。 


在 20 世纪 80 年代 和 90 ERP, ASAT Be HIRAYAMA, BP HRT EK 
戏 。 虽 然 共 享 数 据 还 是 存储 在 文件 服务 器 上 ， 但 是 服务 器 只 负责 处 理 文件 、 行 、 列 和 
索引 。 所 有 的 智能 处 理 都 在 客户 暮 进 行 。 


到 20 世纪 90 年 末期 ， 基 于 个 人 计算 机 网 络 的 应 用 规模 发 展 到 了 极限 ， 客 户 痛 / 服 务 
器 数据 库 开 始 流行 ， 显 示 出 了 极 大 的 可 扩展 潜力 。 

客户 闯 / 服 务 器 数据 库 模 式 在 驱动 富 客 户 痛 应 用 上 只 取得 了 有 限 的 成 功 ， 不 是 因 
为 技术 上 的 问题 ， 而 是 因为 很 多 的 开发 者 没有 接受 足够 的 训练 ， 试 图 把 用 于 ISAM 
(Indexed Sequential Access Method， 索 引 顺 序 访 问 方法 ) 数据 库 的 技术 也 应 用 在 客户 
总/ 服务 器 数据 库 上 。 再 加 上 提供 商 为 获得 可 扩展 性 ， 大 力 推 行 客户 间 / 服 务 器 数据 
库 ， 以 直接 取代 原 有 的 数据 库 系 统 ， 结 果 更 加 限制 了 富 客户 编 的 发 展 。 


Web 应 用 程序 在 新 世纪 开始 兴起 。Web 应 用 把 应 用 程序 的 工作 流 和 业务 远 辑 放 在 了 靠 
近 数 据 的 服务 器 上 ， 取 得 了 成 功 。 这 种 方式 解决 了 基于 个 人 计算 机 的 网 络 的 大 量 通信 
问题 ， 也 避免 了 客户 端 / 服 务 器 数据 库 模 式 难以 处 理 的 一 些 并 发 问题 。 


近年 来 ，JavaScript 从 辅助 基于 HTML 的 Web 体验 ， 发 展 为 创建 和 控制 Web 体验 。 

种 趋势 正在 出 现 ， 将 应 用 程序 的 工作 流 和 逻辑 移 回 客户 闹 ， 但 只 限于 Web 浏览 器 的 运 
行 时 环境 。 

如 果 我 们 要 把 业务 远 辑 移 回 客户 妆 ， 就 必须 理解 这 种 做 法 在 过 去 为 什么 失败 ， 然 后 才 
能 避免 重复 先行 者 们 犯 过 的 错误 。 

在 这 个 关键 的 架构 选择 中 ， 有 具有 超 媒体 能 力 的 媒体 类 型 是 非常 关键 的 一 部 分 ， 这 些 媒 
体 类 型 既 能 够 传递 工作 流 ， 也 能 够 表达 应 用 程序 语义 ， 因 而 工作 负载 能 够 在 客户 阁 和 
服务 器 之 间 进 行 更 加 合理 地 分 布 。 
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示例 6-3 中 的 媒体 类 型 text/csv 为 返回 信息 提供 了 一 些 结构 。 这 个 数据 模型 定义 为 一 组 以 
喜 号 分 隔 的 数值 ， 随 后 拆 分 为 〈 通 常 是 ) 结构 类 似 的 数据 行 。 我 们 还 是 不 知道 这 些 数 据 是 
什么 , 但 是 至 少 能 够 将 数据 格式 化 后 展现 给 用 户 (假设 用 户 知道 自己 看 到 的 是 什么 )。 


示例 6-3: 简单 结构 化 的 数据 
GET /some-mystery-resource 
200 OK 
Content-Type: text/csv 
Content-Length: 29 














59,0 
13,1 
17,30 
8,365 
3,65535 


6.3.2 ”流行 格式 
请 看 示例 6-4。 


示例 6-4: 标记 
GET /some-mystery-resource 
200 OK 
Content-Type: application/xml 
Content-Length: 29 


<root> 
<element attribute1="59" attribute2="0"/> 
<element attribute1="13" attribute2="1"/> 
<element attribute1="17" attribute2="30"/> 
<element attribute1="8" attribute2="365"/> 
<element attribute1="3" attribute2="65535"/> 
</root> 


在 这 个 示例 中 ， 内 容 返 回 格式 是 XML， 这 并 不 比 text/csv 格式 具有 更 多 语义 。 我 们 还 是 
只 有 五 对 数字 ，XML 格式 提供 了 给 这 些 数据 命名 的 地 方 。 可 是 ， 这 些 名 字 的 含义 没有 定 
义 在 application/xml 格式 的 规范 里 ， 因 此 ， 如 果 任 何 客户 端 试 图 给 这 些 名 字 赋 予 意 义 ， 
还 是 需要 依靠 离线 知识 ， 从 而 引入 了 隐藏 的 耦合 。 在 本 章 的 后 面部 分 ， 我 们 将 讨论 其 他 的 
方法 ， 用 于 将 语义 附加 在 通用 媒体 类 型 之 上 ， 而 又 不 创造 隐藏 的 耦合 。 





























对 于 更 为 复杂 的 场景 ，application/xml 格式 可 以 用 于 表达 数据 的 层次 结构 ， 为 文本 块 标记 
附加 信息 。 但 是 ，applicaiton/xml 格式 提供 语义 的 方式 十 分 有 限 ， 这 个 问题 依然 没有 解决 。 


application/json (参见 示例 6-5) 沟通 语义 的 能 力 甚 至 比 application/xml 的 还 要 弱 。 在 
Web 浏览 器 环境 里 使 用 ISON 的 好 处 是 ， 我 们 可 以 下 载 JavaScript 代码 ， 为 文档 实现 语 
义 ， 从 而 使 客户 端 和 服务 器 能 够 同时 演化 。 但 是 这 种 方法 具有 一 个 缺点 ， 只 能 使 用 支持 
JavaScript 运行 时 的 客户 端 。 这 种 方法 也 会 影响 中 间 层 组 件 与 消息 交互 的 能 力 ， 因 而 无 法 
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充分 利用 HTTP 分 层 架 构 的 优点 。 
示例 6-5: 对 象 序列 化 


GET /some-mystery-resource 

200 OK 

Content-Type: application/json 
Content-Length: 29 


{ "objects" : [ 


{"property1"="59", "property2"="0"}, 
{"property1"="13", "property2"="1"}, 
{"property1"="17", "property2"="30"}, 
{"property1"="8", "property2"="365"}, 
{"property1"="3", "property2"="65535"} 


] 
} 


如 果 说 通用 类 型 位 于 媒体 类 型 范围 的 一 端 ， 那 么 接 下 来 要 讨论 的 例子 就 位 于 与 通用 类 型 相 
反 的 另 一 端 。 在 这 个 例子 里 ， 我 们 专门 为 某 个 应 用 程序 定义 了 一 个 新 的 媒体 类 型 ， 人 准确 具 
备 服务 器 理解 的 语义 。 为 了 让 人 们 理解 这 个 类 型 ,我 们 需要 为 这 个 媒体 类 型 编写 一 个 规 
范 ， 发 布 在 因特网 上 ， 最 好 还 要 在 IANA 注册 ， 这 样 的 话 ， 如 果 开 发 者 希望 理解 收 到 的 表 
达 形 式 的 含义 ， 就 能 够 很 容易 找到 这 个 媒体 类 型 的 信息 。 


6.3.3 ”新 格式 


现在 请 看 示例 6-6。 


示例 6-6: 服务 相关 的 格式 
GET /some-mystery-resource 
200 OK 
Content-Type: application/vnd.acme.cache-stats+xml 
Content-Length: ?? 
































<cacheStats> 
<cacheMaxAge percent="59" daysLowerLimit="0" daysUpperLimit="0"> 
<cacheMaxAge percent="13" daysLowerLimit="0" daysUpperLimit="1"> 
<cacheMaxAge percent="17" daysLowerLimit="1" daysUpperLimit="30"> 
<cacheMaxAge percent="8" daysLowerLimit="30" daysUpperLimit="365"> 
<cacheMaxAge percent="3" daysLowerLimit="365" daysUpperLimit="65535"> 
</cacheStats> 











这 个 媒体 类 型 终于 说 明了 ， 我 们 一 直 在 处 理 的 数据 原来 是 一 个 图 形 的 数据 点 系列 ， 用 于 展 
因特网 上 请 求 消 息 的 缓存 控制 标 头 中 有 效 期 长 度 值 的 分 布 。 这 个 媒体 类 型 提供 了 客户 端 
里 这 个 信息 的 图 形 所 需 的 所 有 信息 。 但 是 ， 这 个 媒体 类 型 的 应 用 场合 非常 特殊 。 人 们 多 
入 会 需要 编写 应 用 程序 ， 展 示 缓 存 统计 量 的 图 形 表 示 呢 ? 如 果 要 为 这 个 媒体 类 型 编制 一 个 
规范 ， 并 提交 到 IANA 进行 广 册 ， 似 和 平 有 点 小 题 大 做 了 。 在 今天 ， 绝 大 多 数 的 Web API fill 
建 这 种 使 用 范围 很 窄 的 有 效 载 符 ， 但 并 不 会 费 神 编写 规范 和 申请 注册 。 但 是 ， 我 们 还 有 别 
的 方法 可 以 提供 用 户 所 需 的 所 有 信息 ， 并 且 能 适用 于 更 多 的 场景 。 
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请 看 示例 6-7 中 的 场景 。 


示例 6-7: 领域 相关 的 格式 
GET /some-mystery-resource 
200 OK 
Content-Type: application/data-series+xml 
Content-Length: ?? 


<series xAxisType="range" 
yAxisType="percent" 
title="% of requests with their max-age value in days"> 
<dataPoint yValue="59" xLowerValue="0" xUpperValue="0"> 
<dataPoint yValue="13" xLowerValue="0" xUpperValue="1"> 
<dataPoint yValue="17" xLowerValue="1" xUpperVaLlue="30"> 
<dataPoint yValue="8" xLowerValue="30" xUpperValue="365"> 
<dataPoint yValue="3" xLowerValue="365" xUpperValue="65535"> 
</series> 





在 这 个 示例 中 ， 我 们 创建 了 一 个 媒体 类 型 ， 用 于 传输 绘制 一 个 图 形 需要 的 一 组 数据 点 。 绘 








制 的 图 形 可 能 是 折线 图 、 饼 图 和 直方 图 ， 或 者 直接 就 是 一 个 数据 表 。 客 户 端 可 以 理解 这 些 
数据 点 在 绘制 图 形 方面 的 语义 。 至 于 图 形 展 示 的 是 什么 ， 需 要 人 类 用 户 来 理解 ， 客 户 端 并 
不 知道 。 但 是 ， 这 些 附 加 的 语义 使 客户 端 可 以 进行 一 些 操作 ， 如 : 县 加 图 形 、 切 换 轴 以 及 
放大 图 形 的 某 些 部 分 。 






























































这 个 媒体 类 型 的 可 重用 性 比 application/vnd.acme.cachestats+xml 要 高 得 多 。 任 何 需 要 图 
形 化 展示 数据 的 应 用 场景 都 可 以 使 用 这 个 媒体 类 型 。 为 这 个 媒体 类 型 编写 完整 的 规范 所 付 


出 的 努力 ， 很 快 就 能 得 到 回报 。 








我 认为 ， 这 种 与 领域 相关 ， 但 不 与 服务 相关 的 媒体 类 型 ， 是 媒体 类 型 应 该 传递 的 语义 的 最 
佳 平衡 。 这 种 媒体 类 型 中 ， 有 些 例子 已 证 明 颇 为 成 功 : 


HTML 用 于 传递 超 链 接 文本 文档 ; 
Atom (参见 http://datatracker.ietf.org/doc/rfc4287/) 设计 用 于 整合 基于 Web 的 博客 ，; 
AcitvityStream (参见 http:Wactivitystrea.ms/) 用 于 表示 事件 流 ; 

Json-home (参见 http://tools.ietf.org/html/draft-nottingham-json-home-03) 设计 用 于 发 现 
API 中 可 用 的 资源 ， 

Json-problem (参见 http://tools.ietf.org/html/draft-nottingham-http-problem-03) 设计 用 于 
提供 API 返回 错误 的 细节 。 








以 上 列举 的 所 有 这 些 媒体 类 型 都 有 一 些 共同 点 。 这 些 媒体 类 型 都 包含 用 于 解决 一 个 特定 问 
题 的 语义 ， 但 是 并 不 与 任何 特定 的 应 用 程序 相关 。 每 个 API 都 需要 返回 错误 信息 ， 大 部 分 
的 应 用 程序 都 有 要 用 到 事件 流 的 领域 。 这 些 媒体 类 型 的 定义 完全 与 平台 及 语言 无 关 ， 也 就 
是 说 任何 开发 者 在 任何 类 型 的 应 用 程序 中 都 可 以 使 用 这 些 类 型 。 还 有 很 多 新 的 媒体 类 型 等 
待 我 们 去 定义 ， 在 很 多 的 应 用 程序 中 重用 。 




















媒体 类 型 选择 与 设计 | 101 





6.3.4 超 媒 体 类 型 
超 媒 体 类 型 是 一 类 媒体 类 型 ， 通 常 基 于 文本 ， 并 包含 指向 其 他 资源 的 链接 。 通 过 在 资源 表 
示 中 提供 链接 ， 用 户 代理 可 以 根据 自己 对 链接 含义 的 理解 ， 从 一 个 表示 跳 转 到 另 一 个 表示 。 


























超 媒 体 类 型 对 于 客户 端 和 服务 器 的 分 离 ， 起 到 了 极 大 的 作用 。 通 过 使 用 超 媒 体 ， 客 户 端 不 
再 需要 事先 了 解 Web 上 公布 了 哪些 资源 ， 而 可 以 在 运行 时 刻 发 现 资源 。 





虽然 超 媒 体 在 HTML 中 为 Web 应 用 提供 的 好 处 显而易见 ， 但 它 在 Web API 开发 中 起 到 的 
作用 却 微 不 足 道 。 因 为 缺乏 工具 ， 认 为 链接 会 不 必要 地 增加 资源 表示 的 大 小 ， 以 及 普遍 缺 
乏 对 超 媒 体 优 点 的 认同 ，Web 应 用 程序 的 开发 者 们 往往 会 避免 使 用 超 媒体 。 











在 有 些 情 况 下 ， 例 如 : 性 能 要 求 很 高 时 ， 使 用 超 媒体 并 不 合适 。 对 于 性 能 要 求 高 的 系统 ， 
HTTP 协议 可 能 也 不 是 最 佳 选择 。 而 当 可 演化 性 是 一 个 基于 HTTP 系统 的 关键 目标 时 ， 我 
们 绝 不 能 忽略 超 媒体 的 作用 。 


6.3.5 ”媒体 类 型 爆炸 

到 这 里 ， 我 们 已 经 了 解 了 通用 媒体 类 型 如 何 需 要 离线 知识 提供 语义 ， 也 看 到 了 携带 领域 相 
关 语 义 的 较为 特殊 的 媒体 类 型 示例 。 在 Web 开发 社区 中 ， 一些 人 不 愿意 鼓励 大 家 创建 3 
的 媒体 类 型 ， 害 怕 产 生 “ 媒 体 类 型 爆炸 ”一 一 创建 大 量 的 新 媒体 类 型 会 产生 设计 糟糕 的 规 
范 、 重 复工 作 和 服务 相关 的 类 型 ， 而 且 偶 然 重 用 的 可 能 性 会 大 大 降低 。 这 种 担心 不 是 没有 
根据 的 ， 媒 体 类 型 有 可 能 会 和 物种 一 样 演化 ， 强 者 生存 ， 弱 者 消亡 。 


6.3.6 通用 媒体 类 型 和 档案 
有 些 人 喜欢 采取 另外 一 种 使 用 媒体 类 型 的 方式 。 其 基本 做 法 是 ， 使 用 一 个 较为 通用 的 媒体 
类 型 ， 然 后 采取 辅助 方法 在 它 的 表示 之 上 县 加 语义 。 


























这 种 方法 的 一 个 例子 是 RDF (Resource Description Framework， 资 源 描述 框架 ， 参 见 http:/ 
www.w3.org/RDF/) 媒体 类 型 。 简 单 说 来 ， RDF 允许 你 使 用 三 元 组 做 出 声明 ， 即 : 主体 、 
客体 和 谓词 ， 其 中 谓词 描述 了 主体 和 客体 之 间 的 关系 。RDF 表示 的 语义 中 ， 主 要 部 分 由 标 
准 的 谓词 提供 ， 谓 词 的 含义 有 文档 说 明 。RDF 规范 将 信息 片段 关联 在 一 起 ， 但 是 规范 自身 
并 没有 定义 任何 具体 的 领域 语法 。 








示例 6-8 是 来 自 维 基 百 科 的 RDF 条 目 (参见 http://en.wikipedia.org/wiki/Resource_Description_ 
Framework)， 其 中 的 URIhttp://purl.org/dc/elements/1.1 指向 都 柏林 核心 元 数据 启动 计划 
(Dublin Core Metadata Initiative，DCMI) 提供 的 一 份 单词 表 。 





示例 6-8: RDF 示例 
<rdf:RDF 
xmlns:rdf="http: //www.w3.org/1999/02/22-rdf-syntax-ns#" 





xmlns:dc="http://purl.org/dc/elements/1.1/"> 
<rdf:Description rdf:about="http://en.wikipedia.org/wiki/Tony_Benn"> 
<dc:title>Tony Benn</dc:title> 
<dc: publisher>Wikipedia</dc:publisher> 
</rdf:Description> 
</rdf:RDF> 


史 用 又 加 语义 方法 的 另 一 个 例子 是 使 用 ALPS (Application-Level Profile Semantics, Wz} 
层 档案 语义 ， 参 见 http://alps.io/spec/)。ALPS 用 于 指定 可 以 应 用 在 一 个 基础 媒体 类 型 (如 
XHTML) 上 的 领域 语义 ， 如 示例 6-9 所 示 。 使 用 最 近 成 为 标准 的 链接 关系 profile， 可 以 
把 这 种 额外 的 语义 规范 附加 到 已 有 的 媒体 类 型 之 上 。 








示例 6-9: XHTML 上 的 ALPS 


GET /some-mystery-resource 

200 OK 

Content-Type: application/xhtml 
Content-Length: 29 


<html> 
<head> 
<link rel="profile" href="http://example.org/profiles/stats" /> 
</head> 
<title>% of requests with their cache-control: max-age value in days </title> 
<body> 
<table class="data-series"> 
<thead> 
<td>from</td> 
<td>to (days)</td> 
<td>percent</td> 
</thead> 


<tr class="data-point"> 
<td class="xLowerValue"></td> 
<td class="xUpperValue">0</td> 
<td class="yValue">59</td> 

</tr> 

<tr class="data-point"> 


<td class="xLowerValue">0</td> 

<td class="xUpperValue">1</td> 
<td class="yValue">13</td> 

</tr> 

<tr class="data-point"> 
<td class="xLowerValue">1</td> 
<td class="xUpperValue">30</td> 
<td class="yValue">17</td> 

</tr> 

<tr class="data-point"> 
<td class="xLowerValue">30</td> 
<td class="xUpperValue">365</td> 
<td class="yValue">8</td> 

</tr> 

<tr class="data-point"> 
<td class="xLowerValue">365</td> 
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<td class="xUpperValue"></td> 
<td class="yValue">3</td> 
</tr> 
</table> 
</body> 
</html> 


GET http://example.org/profiles/stats 
200 OK 
Content-Type: application/alps+xml 


<alps version="1.0"> 
<doc format="text"> 
Types to support the domain of statistical data 
</doc> 


<descriptor id="data-series" type="Semantic"> 
<descriptor id="data-point" type="semantic"> 
<doc>A data point</doc> 

<descriptor id="xValue" type="semantic""> 
<doc>X value on graph</doc> 

</descriptor> 

<descriptor id="xLowerValue" type="semantic"> 
<doc>Lower bound on X range of values</doc> 

</descriptor> 

<descriptor id="xUpperValue" type="semantic"> 
<doc>Upper bound on X range of values</doc> 

</descriptor> 

<descriptor id="yValue" type="semantic" > 
<doc>Y value on graph</doc> 

</descriptor> 

<descriptor id="yLowerValue" type="semantic"> 
<doc>Lower bound on Y range of values</doc> 

</descriptor> 

<descriptor id="yUpperValue" type="semantic"> 
<doc>Upper bound on Y range of values</doc> 

</descriptor> 

</descriptor> 

</descriptor> 


</alps> 





示例 6-10 中 展示 的 HAL (Hypermedia Appliation Language， 超 媒体 应 用 程序 语言 ， 参 见 http:/ 
stateless.co/hal_specification.html) ， 是 一 种 使 用 链接 关系 来 应 用 领域 语义 的 通用 媒体 类 型 。 


示例 6-10: application/hal+xml 和 application/hal+json 中 的 HAL 


<resource xAxisType="range" 
yAxisType="percent" 
title="% of requests with their max-age value in days"> 
<resource rel="http://example.org/stats/data-point" 
yValue="59" 
xLowerVaLlue="0" 





xUpperValue="0"> 

<resource rel="http://example.org/stats/data-point" 
yValue="13" 
xLowerVaLue="0" 
xUpperVaLue="1"> 

<resource rel="http://example.org/stats/data-point" 
yValue="17" 
xLowerValLue="1" 
xUpperVaLue="30"> 

<resource rel="http://example.org/stats/data-point" 
yValue="8" 
xLowerVaLue="30" 
xUpperVaLue="365"> 

<resource rel="http://example.org/stats/data-point" 
yValue="3" 
xLowerValue="365" 
xUpperVaLue="65535"> 


</resource> 
{ 
"xAxisType" : "range", 
"yAxisType" : "percent", 
"title" : n% of requests with their max-age value in days", 
"_embedded" : { 
"http://example.org/stats/data-point" 
{ "yValue" : "59", "xLowerValue" : "0", "xUpperValue" : "0"}, 
"http://example.org/stats/data-point" 
{ "yValue" : "13", "xLowerValue" : "0", "xUpperValue" : "1"}, 
"http://example.org/stats/data-point" 
{ "yValue" : "17", "xLowerValue" : "1", "xUpperValue" : "30"}, 
"http://example.org/stats/data-point" 
{ "yValue" : "8", "xLowerValue" : "30", "xUpperValue" : "365"}, 
"http://example.org/stats/data-point" 
{ "yValue" : "3", "xLowerValue" : "365", "xUpperValue" : "65535"} 
} 
} 


HAL 依靠 链接 关系 提供 所 需 的 语义 ， 对 资源 表示 中 非 HAL 的 部 分 进行 解释 。 这 意味 着 ， 
链接 关系 类 型 http://example.org/stats/data-point 的 文档 需要 对 yValue, xLowerValue 
和 xUpperValue 进行 定义 。HAL 并 不 关心 这 些 值 是 属性 还 是 元 素 ，HAL 文档 的 使 用 者 负责 

发 现 这 些 信息 存储 的 具体 位 置 。 


使 用 链接 关系 来 传递 语义 的 一 个 问题 是 ， 端 点 URI 经 常 没有 链接 关系 。 你 如 果 在 浏览 器 
地 址 栏 中 输入 一 个 链接 地 址 ， 不 会 看 到 链接 关系 。 对 此 有 几 种 规避 方法 : 你 可 以 限制 根 资 
源 ， 仅 使 用 岁入 资源 和 链接 ， 或 者 你 可 以 使 用 链接 关系 type， 把 语义 联系 到 根 资 源 。 


使 用 通用 的 媒体 类 型 的 好 处 是 ， 生 成 、 解 析 和 展示 这 些 格式 的 工具 很 可 能 已 经 存在 ， 可 以 
重用 。 而 且 你 可 以 定义 语义 档案 ， 映 射 到 多 个 不 同 的 基础 媒体 类 型 。 如 果 某 个 媒体 类 型 更 
加 适合 在 某 个 平台 使 用 ， 就 会 更 有 优势 。 而 在 定义 领域 相关 的 媒体 类 型 时 ， 如 果 需 要 同时 
支持 XML Fil ISON 的 类 型 变种 ， 你 就 必须 编写 两 份 媒体 类 型 规范 ， 因 为 格式 和 语义 都 是 
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由 媒体 类 型 定义 的 。 


人 们 正在 试图 规范 描述 语义 档案 的 流程 (参见 http://alps.io/spec/index.html)， 有 可 能 会 制 
定 多 个 可 行 的 方案 。 


使 用 通用 媒体 类 型 与 辅助 语义 档案 相 结 合 的 方法 ， 有 一 个 缺点 是 中 间 层 组 件 难以 了 解 消息 
的 语义 。HTTP 架构 中 的 任何 一 层 都 可 以 轻易 处 理 Content-Type 标 头 中 指定 的 媒体 类 型 。 
如 果 使 用 如 链接 关系 和 档案 的 技术 进行 语义 附加 ， 中 间 层 就 难以 发 现 语义 信息 ， 无 法 基于 
这 些 信息 进行 处 理 。 在 Web 架构 中 ， 完 成 事情 的 方法 通常 不 止 一 个 ， 各 种 方法 都 有 各 自 的 
优 缺 点 ， 因 此 ， 我 们 必须 合理 设计 系统 ， 以 满足 需求 。 


辅助 语义 档案 的 使 用 是 一 个 值得 关注 的 领域 。 未 来 可 期 待 出 现 更 成 熟 的 方法 ， 进 行 消息 语 
义 的 定义 。 


从 前 面 列举 的 示例 中 ， 你 可 以 看 到 ， 在 客户 端 和 服务 器 间 传 递 同样 的 数据 有 很 多 种 方法 可 
用 。 有 些 媒 体 类 型 携带 较 多 的 语义 信息 ， 有 些 则 较 少 。 使 用 多 少 应 用 相关 的 语义 驱动 客户 
端 ， 取 决 于 是 否 存在 标准 的 媒体 类 型 满足 你 的 需求 ， 以 及 你 对 耦合 性 的 容忍 度 。 


6.3.7 ”其 他 超 媒体 类 型 


过 去 几 年 出 现 了 一 些 新 的 超 媒 体 类 型 。 接 下 来 的 小 市 介绍 了 其 中 几 个 类 型 。 






































1. Collection+JSON 

Collection+JSON 媒体 类 型 适用 于 列表 的 应 用 领域 。 这 个 类 型 既 通 用 又 特殊 ， 非 常 有 趣 。 
Collecion+JSON 只 支持 列表 ， 但 是 并 不 关心 列表 中 的 东西 是 什么 。 这 个 类 型 还 提供 有 趣 的 
语义 提示 ， 可 以 描述 如 何 查询 列表 以 及 添加 新 条 目 。 这 个 类 型 对 列表 中 的 条 目 提供 的 语义 
虽然 极为 简单 ， 但 是 支持 档案 标记 ， 可 用 于 描述 列表 中 的 条 目 。 





2. Siren 

Siren (参见 https://github.com/kevinswiber/siren) 是 另 一 个 很 新 的 超 媒体 类 型 ， 类 似 HAL, 
(RG A RAKE BE AKA Pe, Siren 与 HAL 的 不 同 之 处 在 于 ，Siren 把 语义 附加 在 
数据 元 素 上 。Siren 借用 了 HTML 的 class 标记 ， 用 于 标识 语义 信息 。Siren 还 对 用 于 浏览 
资源 的 链接 和 代表 行为 的 链接 做 了 区 分 。action 链接 也 有 自己 的 链接 提示 风格 ， 告 诉 客 户 
端 如 何 调用 这 个 action, 

虽然 有 人 认为 ， 大 家 应 该 统一 使 用 一 种 格式 ， 但 是 我 情愿 让 自然 选择 产生 结果 ， 而 不 是 试 
图 强制 所 有 的 场景 都 使 用 一 个 超 媒体 格式 。HTTP 使 API 更 容易 支持 一 个 资源 的 多 个 表示 ， 
客户 端 可 以 从 中 进行 选择 ， 因 此 ， 使 用 多 种 格式 不 会 成 为 系统 发 展 的 严重 障碍 。 

到 目前 为 止 ， 我 们 主要 把 媒体 类 型 作为 一 种 沟通 语义 的 方法 进行 讨论 ， 但 是 正如 在 讨论 
HAL 时 提 到 的 ， 语 义 也 可 以 通过 链接 关系 来 传递 。 下 一 市 将 进一步 讨论 链接 关系 。 
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6.4 ”链接 关系 类 型 
在 前 面 介绍 协议 类 型 的 部 分 ， 我 提 到 链接 关系 类 型 说 明了 你 为 什么 可 能 对 某 个 资源 感 兴趣 。 


链接 关系 类 型 是 在 HTML 中 首先 引入 的 。 最 常见 的 链接 关系 类 型 大 概 就 是 rel="styles 
heet 了 ， 这 个 值 把 一 个 HTML 页 面 和 辅助 展示 这 个 页 面 的 样式 表 联 系 在 了 一 起 : 



































<link href="..." media="all" rel="stylesheet" type="text/css" /> 


不 久之 前 ， 人 们 对 链接 关系 类 型 进行 了 完整 的 定义 ， 制定 了 RFC 5988 (参见 http://tools. 
ietf.org/html/rfc5988) 规范 。 


6.4.1 语义 

媒体 类 型 承载 的 语义 可 以 非常 通用 ， 链 接 关 系 也 是 如 此 。 有 些 标 准 化 的 链接 关系 类 型 非常 
通用 ， 如 next, previous, current, item, collection, first 和 Tast。 但 是 ， 这些 通用 类 
型 确实 提供 了 相关 资源 的 重要 上 下 文 信息 。 男 一 方面 ， 有 些 标准 化 的 链接 关系 的 用 途 非常 


HAH, “help, monitor, payment, license, copyright 和 terms-of-service, 





查看 链接 关系 标准 注册 表 (参见 hittp://www.iana.org/assignments/link-relations/link-relations. 
xml) 并 不 能 帮助 我 们 完全 了 解 链接 关系 的 功能 。 大 部 分 的 标准 链接 关系 都 没有 定义 任何 的 
行为 或 者 约束 ， 只 是 简单 指明 了 目标 资源 ， 或 者 描述 了 上 下 文 资源 与 目标 资源 之 间 的 关系 。 














政 治 
如 果 你 对 Web 和 因特网 规范 略 加 了 解 ， 立 刻 就 会 发 现 其 中 涉及 很 多 政治 因素 。 我 得 警 
告 你 ， 我 本 人 倾向 于 主张 由 IETF (Internet Engineering Task Force， 因 特 网 工程 任务 组 ) 
管理 因特网 相关 的 规范 。IETF 采用 IANA 进行 注册 管理 ， 因 此 我 以 IJANA 媒体 注册 表 和 
IANA 链接 关系 注册 表 为 标准 。 但 是 ， 有 些 组 织 并 不 满意 IETFIANA 的 注册 流程 ， 而 选 
择 使 用 另 一 种 链接 关系 的 注册 表 (参见 http://microformats.org/wiki/existing-rel-values) 。 











有 一 些 链接 关系 除了 能 标识 关系 ， 还 开始 给 出 更 多 的 用 途 。 让 我 们 看 看 noreferrer 和 
prefetch, noreferrer 告诉 用 户 代理 ， 如 果 使 用 这 个 链接 ， 就 不 应 该 指定 referer 标 头 ; 
prefetch 告诉 用 户 代 理 ， 在 用 户 请 求 使 用 这 个 链接 之 前 ， 用 户 代 理应 该 先 获取 目标 资源 ， 
使 缓存 中 已 有 资源 表示 。 在 这 两 个 例子 中 ， 链 接 关系 实际 上 告诉 了 用 户 代理 ， 服 务 器 希望 
用 户 代 理 如 何 与 这 个 链接 进行 交互 。 链 接 关系 能 提供 更 多 的 信息 。 一 个 链接 关系 类 型 的 
规范 可 以 表明 某 个 链接 只 使 用 POST 方法 ， 或 者 说 明 当 访问 链接 时 ， 返 回 的 资源 表示 总 是 
application/json 格式 的 。 


有 些 人 选择 不 在 链接 关系 类 型 的 规范 中 定义 交互 机 制 ， 而 是 在 链接 中 读 入 元 数据 ， 告 诉 客 
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户 端 如 何 与 链接 进行 交互 。 例 如 : HTML 的 <FORM> 标签 有 一 个 方法 属性 ， 告 诉 浏览 器 使 
用 GET 或 者 P05T 方 法。 另 一 种 方法 是 使 用 链接 提示 ， 服 务 器 可 以 舱 入 元 数据 ， 给 出 如 何 使 
用 链接 的 建议 。 不 过 ， 这 并 不 排除 使 用 链接 的 其 他 有 效 方法 。 


所 有 这 些 方法 都 可 以 用 于 向 客户 端 说 明 链 接 机 制 。 可 重用 度 最 高 的 方法 是 ， 使 用 比较 通用 
的 链接 关系 蔡 入 元 数据 ， 但 是 这 种 方法 传输 的 数据 量 最 大 ， 而 且 可 能 会 减少 客户 端 需要 了 
解 的 链接 关系 数量 。 如 果 使 用 明确 的 链接 关系 ， 提 供 文档 中 定义 的 所 有 交互 细节 ， 那 么 使 
用 的 带宽 较 少 ， 但 是 对 客户 端 应 用 程序 的 要 求 更 高 。 


如 果 把 使 用 明确 的 链接 关系 这 一 想法 发 挥 到 极致 ， 一 个 链接 关系 address 可 以 要 求 使 用 
GET 方 法 ， 然 后 返回 格式 为 application/json 的 资源 ， 包 括 属性 street, city, state, 
country、 和 zipcode。 链 接 关系 定义 的 约束 越 多 ， 可 重用 性 就 越 低 ， 管 理 注册 表 的 主题 
专家 基本 不 可 能 接受 这 样 的 链接 关系 。 但 是 ， 有 一 种 扩展 链接 关系 类 型 (extended link 
relation type), "JLAM URI 作为 标识 符 ， 唯 一 标识 这 个 关系 。 使 用 扩展 链接 关系 类 型 时 ， 
你 不 需要 在 IANA 注册 链接 关系 ， 可 以 随意 进行 定义 。 


使 用 链接 关系 精确 描述 预期 的 响应 有 一 个 有 趣 的 效果 ， 可 以 不 依赖 离线 知识 ， 使 用 如 
application/xml 和 application/ json 等 通用 类 型 传递 数据 。 





























但 是 ， 我 个 人 的 经 验 是 ， 如 果 由 链接 关系 和 媒体 类 型 均匀 分 担 语义 信息 ， 产 生 的 协议 类 型 
可 重用 性 会 更 高 。 





链接 关系 和 媒体 类 型 的 合作 方式 类 似 自 然 语 言 中 的 形容 词 和 名 词 。 形 容 词 快乐 的 可 以 与 很 
多 名 词 一 起 使 用 。 把 独立 的 形容 词 和 名 词 结合 在 一 起 ， 可 以 避免 产生 大 量 的 新 名 词 ， 如 : 
RRA, RAF. RRS, SE, 








{ "collection" : 


{ 
"version" : "1.0", 
"href" : "http://example.org/journal/?fromDate=20130921&toDate=20130922" 
"items" : [ 
{ 
"href" : "http://example.org/transaction/794", 
"data" : [ 
{"amount" : "14576", "currency" : "USD", "date" : "20130921"} 
l; 
"Links" : [ 
{"rel" : "origin", "href" : "http://examples.org/account/bank1000"}, 
{"rel" : "destination", 
"href" : "http://examples.org/account/payables/HawatiTravel"} 
] 
Fs 
"items" [ 
{ 
"href" : "http://example.org/transaction/794", 
"data" : 





{"amount" : "150000", "currency" : "USD", "date" : "20130922"} 


links" : [ 
{"rel" : "origin", 
"href" : "http://examples.org/account/receivables/acme"}, 
{"rel" : "destination", 
"href" : "http://examples.org/account/bank1000"} 
] 
} 


} 
} 
举 个 例子 ， 假 设 我 们 要 注册 两 个 链接 关系 类 型 origin 和 destination, FERS HUT, R 
们 都 需要 表示 某 物 从 哪里 来 和 到 哪里 去 一 一 不 管 是 文件 副本 、 银 行 转账 还 是 地 图 上 的 一 条 
道路 。 同 样 的 链接 关系 可 以 重用 在 很 多 不 同 场景 中 。 有 时 候 ， 不 管 链接 具体 指向 什么 ， 这 
些 可 重用 关系 的 语义 就 足以 在 客户 端 上 实现 通用 的 功能 。 这 种 特点 和 面向 对 象 开发 中 的 多 
形 性 颇 为 类 似 。 


通常 ， 当 人 们 想到 超 媒体 档案 中 的 链接 时 ， 他 们 想到 的 是 对 领域 概念 之 间 的 关系 进行 定 
义 。 在 链接 数据 中 ， 链 接 的 主要 用 途 就 是 定义 概念 之 间 的 关系 。 但 是 ， 我 们 也 可 以 使 用 链 
接 实现 更 多 功能 ， 而 不 仅仅 是 声明 域 中 的 关系 。 


6.4.2 ”替换 其 入 资源 

在 HTML 世界 中 ， 我 们 习惯 创建 链接 ， 指 向 图 像 、 脚 本 和 样式 表 。 但 是 ， 我 们 很 少见 到 
API 中 公开 这 种 静态 资源 。 通 过 巧妙 利用 客户 端的 私有 缓存 ，API 可 以 有 效 地 提供 各 种 信 
息 的 静态 资源 。 通 常情 况 下 ， 这 些 信 息 原本 都 用 入 在 客户 端 应 用 程序 中 。 






































6.4.3 间接 层 
链接 可 以 提供 一 层 间 接 性 。 如 果 我 们 在 API 的 入 口 点 创建 发 现 文档 ， 客 户 端 可 以 动态 发 现 
特定 资源 的 位 置 ， 无 需 把 URI 硬 编码 到 客户 端 应 用 程序 中 (参见 示例 6-11)。 





示例 6-11: GitHub 的 一 个 发 现 资源 
GET https://api.github.com/ 


"current_user_url":"https://api.github.com/user", 
"authorizations_url":"https://api.github.com/authorizations", 
"emails_url":"https://api.github.com/user/emails", 
"emojis_url":"https://api.github.com/emojis", 
"events_urLl":"https://api.github.com/events", 


"user_search_url":"https://api.github.com/legacy/user/search/{keyword}" 


} 
有 了 这 个 间接 层 ， 服 务 器 可 以 重新 组 织 URI 结构 ， 客 户 端 无 需 进 行 改 动 。 假 设 GitHub 要 
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允许 通过 地 址 搜索 用 户 ， 就 可 以 在 发 现 资源 中 做 如 下 修改 : 





"user_search_url":"https://api.github.com/legacy/user/search{?keyword,country}" 


假设 客户 端的 设计 遵循 了 URI 模板 (RFC 6570) 的 令 牌 替换 (token replacement) 规则 ， 
我 们 就 不 需要 为 适应 这 个 新 URI 格式 进行 客户 端 改动 。 


我 们 也 可 以 使 用 间接 层 提供 一 种 智能 负载 均衡 。 如 果 某 些 资源 给 服务 器 带 来 了 不 合 比例 的 
大 量 负载 ， 我 们 可 以 修改 URI， 指 向 有 容量 的 替代 服务 器 。 当 不 同类 型 的 请 求 产 生 不 同类 
型 的 有 效 载 集 时， 这 种 负载 均衡 方法 会 发 挥 一 定 的 作用 。 


间接 层 还 可 以 用 于 找到 地 理 位 置 不 同 的 资源 。 使 用 基于 IP 地 址 的 客户 端 地 址 ， 响 应 消息 
中 的 表示 可 以 包含 链接 ， 指 向 地 理 位 置 靠近 客户 端的 服务 器 。 远 距离 上 的 网 络 延迟 可 能 很 
长 ， 因 而 这 种 方法 可 能 很 重要 。 从 位 于 美国 西岸 的 客户 端 访 问 东 岸 的 服务 器 ， 大 约 需 要 80 
上 毫秒。 在 有 很 多 的 资源 可 以 线 取 以 展示 用 户 界面 时 ， 终 端 用 户 很 快 就 能 察觉 到 其 存在 。 



































6.4.4 引用 数据 

数据 输入 的 界面 常常 向 用 户 提 供 选 项 列表 。 这 些 列表 不 需要 在 客户 端 应 用 中 预先 定义 ， 实 
际 上 ， 客 户 端 甚至 不 需要 事先 知道 哪个 列表 与 某 个 输入 字段 相关 。 客 户 端 应 用 程序 可 以 用 
选项 列表 的 链接 标记 一 个 输入 字段 ， 以 此 确定 可 用 的 条 目 列表 ， 而 无 需 对 输入 域 有 所 了 解 。 


例如 : 


<InputForm> 
<Street>/<Street> 
<City></City> 
<Province domainUrl="http://api.example.org/lists/provinces&country=CAN"/> 
<Country>Canada</Country> 
</InputForm> 


HTML 表单 把 整个 列表 代入 在 输入 元 素 中 ， 以 实现 类 似 的 功能 ， 但 是 这 种 方法 效率 并 不 
高 。 使 用 链接 可 以 减少 有 效 载荷 的 大 小 。 有 时 候 ， 某 些 信 息 不 经 常 使 用 ， 可 以 移 到 另 一 个 
资源 中 。 如 果 不 需 要 附加 信息 ， 你 可 以 不 提取 这 些 信 息 ， 这 样 通常 能 够 抵消 二 次 通讯 的 额 
外 开销 。 


数据 易 变 性 的 差别 是 拆 分 资源 的 第 二 个 原因 。 如 果 设 备 传感器 读数 的 资源 表示 中 包含 设备 
的 所 有 配置 细节 ， 会 造成 浪费 ， 因 为 传感器 读数 比 设备 配置 信息 的 变化 要 频 党 得 多 。 我 们 
可 以 在 资源 表示 中 添加 一 个 链接 ， 指 向 设备 配置 细节 ， 用 户 只 在 需要 的 时 候 使 用 即 可 。 


拆 分 资源 的 第 三 个 原因 是 重用 。 我 们 前 面 给 出 的 地 址 /省份 列表 的 例子 就 属于 这 种 情况 。 
对 任何 加 拿 大 地 址 ， 省 份 列表 都 是 一 样 的 。 如 果 一 个 用 户 要 输入 多 个 地 址 ， 那 么 利用 客户 
端 缓存 中 的 省 份 列表 就 可 以 提高 效率 。 
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6.4.5 工作 流 

在 基于 REST 的 系统 中 ， 最 独特 的 特征 之 一 可 能 就 是 应 用 程序 工作 流 的 定义 和 沟通 方式 。 
在 基于 RPC 的 系统 中 ， 客 户 端 必须 理解 应 用 程序 的 交互 协议 。 例 如 : 客户 端 必须 知道 ， 在 
调用 send 之 前 要 调用 open， 结 束 时 要 调用 close。 这 些 规则 必须 事先 在 客户 端 实现 ， 任 何 
动态 的 状态 检测 都 必须 是 定制 的 。 


嵌入 在 资源 表示 中 的 链接 ， 可 以 根据 状态 告诉 客户 端 哪些 交互 是 可 行 的 。 客 户 端 必 须知 道 
所 有 交互 的 类 型 ， 以 便 能 够 使 用 这 些 交互 ， 但 是 不 必 再 费 功夫 去 了 解 什么 时 候 可 以 进行 某 
种 类 型 的 请 求 。 


请 看 示例 6-12， 是 和 前 面 所 举例 子 同样 使 用 超 媒体 的 场景 。 
示例 6-12: 使 用 超 媒 体 定义 工作 流 


GET /deviceApi 
200 OK 
Content-Type: application/hal+xml 

















<resource> 
<link rel="http://example.org/rels/open" href="/deviceApi/sessions"/> 
</resource> 


POST /deviceApi/sessions 
Content-Length: 0 


201 Created Session 
Content-Type: application/hal+xml 
Location: http://example.org/deviceApi/session/1435 


<resource> 
<link rel="http://example.org/rels/send" href="/deviceApi/session/1435{?message}"/> 
<link rel="http://example.org/rels/close" href="/deviceApi/session/1435"/> 
</resource> 


DELETE /deviceApi/session/1435 
200 OK 


虽然 客户 端 还 是 需要 理解 open/send/ctose 链接 关系 ， 但 是 服务 器 可 以 引导 客户 端 完 成 工 
作 流 程 。 客 户 端 必须 知道 ,激活 open 链接 ， 需 要 发 送 一 个 没有 正文 的 PosT 请 求 ， 激活 
close 链接 ， 需 要 使 用 DELETE 方法 。 在 这 个 示例 中 ， 啊 应 消息 使 用 的 是 HAL 格式 ， 但 是 
服务 器 完全 可 以 返回 多 种 超 媒 体格 式 。 链 接 关 系 不 必 限 制 返回 的 媒体 类 型 。 但 是 ， 客 户 端 
至 少 需要 理解 服务 器 返回 的 其 中 一 种 媒体 类 型 。 


如 果 客 户 端 设计 为 可 使 用 动态 的 链接 ， 那 么 客户 端 就 可 以 适应 工作 流 中 的 变化 。 例 如 : 客 
户 端 使 用 一 种 算法 ， 首 先 寻 找 send 链接 ， 如 果 没 有 找到 send 链接 则 寻找 open 链接 ， 使 
用 open 链接 ， 然 后 再 寻找 send。 采 用 这 种 方法 ， 如 果 API 的 新 版 本 不 再 需要 使 用 open/ 
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ctose， 那 么 我 们 就 可 以 修改 原 有 的 /deviceApi 资源 表示 ， 直 接 包含 send 链接 。 客 户 端 能 
够 自动 适应 这 个 新 协议 ， 不 做 改动 就 能 继续 工作 。 

这 个 示例 非常 的 人 简单。 复杂 应 用 程序 的 交互 协议 会 更 为 复杂 ， 有 更 多 的 机 会 利用 这 种 动态 
的 工作 流 功 能 。 





6.4.6 语法 

RFC 5988 也 定义 了 在 HTTP 标 头 中 幅 入 链接 的 格式 ， 因 此 ， 即 使 是 使 用 二 进 制 内 容 (如 
图 像 和 视频 )， 你 也 可 以 在 返回 的 资源 表示 中 包含 超 媒 体 。 但 是 ，RFC 5988 没有 定义 链接 
应 该 如 何 嵌 入 其 他 的 媒体 类 型 。 链 接 如 何 进 行 序列 化 ， 必 须 由 媒体 类 型 规范 自己 定义 。 像 
application/json FH application/xml 这 样 的 媒体 类 型 没有 定义 链接 应 该 如 何 表示 ， 因 此 
使 用 起 来 可 能 会 有 问题 。 人 们 使 用 过 一 些 不 同 的 方法 ， 但 是 因为 缺少 正式 的 规范 ， 很 难 写 
出 可 重用 的 代码 进行 链接 解析 。 有 些 和 争论 看 似 微不足道 ， 但 是 也 需要 定义 ， 我 就 曾 看 到 人 
们 为 了 JSON 对 象 应 该 叫 作 Links 还 是 _Links 而 辩论 好 几 个 小 时 。 





























下 面 是 一 些 链接 语法 的 示例 ; 











application/hal+json 


"links": { 
"self": { "href": "/orders" }, 
"next": { "href": "/orders?page=2" }, 
"find": { 
"href": "/orders{?id}", 
"templated": true 


F; 
"admin": [{ 
"href": "/admins/2", 
"title": "Fred" 
H 
ks 


application/collection+json 
"Links" : [ 
{"rel" : "blog", "href" : "http://examples.org/blogs/jdoe", 
"prompt" : "Blog"}, 
{"rel" : "avatar", "href" : "http://examples.org/images/jdoe", 
"prompt" : "Avatar", "render" : "image"} 


] 
application/vnd.github.v3+json 


"assignee": { 


"Login": "octocat", 

"td": f; 

"avatar_url": "https://github.com/images/error/octocat_happy.gif", 
"gravatar_id": "somehexcode", 


"url": "https://api.github.com/users/octocat" 





} 


application/hal+xml 
<link rel="admin" href="/admins/5" title="Kate" /> 


application/atom+xml 

<link href="http://www.example.org/data/qiw2e3r4" rel="related" hreflang="en" /> 
<collection href="http://example.org/blog/main" /> 

<content src="http://www.example.org/blog-posts/123" /> 

<icon>http: //www.example.org/images/icon</icon> 


text/html 

<link rel="stylesheet" type="text/css" 
href="http://cdn2.sstatic.net/stackoverflow/all.css?v=c9b143e6d693"> 

<a href="/faq">faq</a> 


<form id="search" action="/search" method="get" autocomplete="off"> 


<div> 
<input autocomplete="off" name="q" class="textbox" 
placeholder="search" tabindex="1" type="text" 
maxlength="240" size="28" value=""> 
</div> 


</form> 


从 这 些 示例 可 以 看 到 ， 超 媒体 表示 中 的 链接 可 以 采用 多 种 形式 。 我 希望 在 未 来 几 年 能 看 到 
更 多 的 格式 合并 ,减少 一 些 表示 上 的 差异 。 值 得 注意 的 是 ， 虽 然 这 些 示 例 中 很 多 都 没有 
rel 属性 ， 但 却 具 有 链接 关系 类 型 的 概念 。 以 HTML 为 例 ， 一 个 <a> 标签 可 以 很 简单 地 表 
示 为 如 下 形式 : 





<link rel="a" href=" /faq" /> 
同样 ，<FORM> 标签 可 以 表示 为 : 


<link rel="form" id="search" action="/search" method="get" autocomplete="off"> 


<div> 
<input autocomplete="off" name="q" class="textbox" 
placeholder="search" tabindex="1" type="text" 
maxLlength="240" size="28" value=""> 
</div> 


</link> 


这 两 种 风格 只 是 演示 了 定义 链接 关系 语法 的 两 种 不 同 廊 式 。 有 些 人 在 使 用 RFC 5988 定义 
链接 关系 时 会 遇 到 一 些 问题 ， 我 们 也 可 以 使 用 这 两 种 方式 对 此 加 以 规避 。 按 照 RFC 5988 
的 规定 ， 为 了 使 用 一 个 简单 的 标记 ， 如 rel="destination"， 你 必须 在 IANA 注册 这 个 关 
系 ， 也 就 是 说 要 接受 一 项 由 领域 专家 进行 的 审查 。IANA 注册 表 的 目的 是 为 了 鼓励 人 们 开 
发 适用 于 不 同 媒体 类 型 中 的 链接 关系 。 正 如 之 前 提 到 的 ， 你 可 以 使 用 扩展 媒体 类 型 的 概 
念 ， 创 建 一 个 使 用 URI 的 链接 关系 。 但 是 ，URI 可 能 会 很 长 ， 在 资源 表示 中 过 于 花哨 。 如 
果 你 想 创建 一 个 专门 供 某 个 媒体 类 型 使 用 的 链接 关系 ， 那 么 可 以 选择 使 用 如 下 的 序列 化 : 
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<family> 
<mother href="/people/bob"/> 
<father href="/people/mary"/> 
</family> 
使 链接 关系 类 型 成 为 媒体 类 型 语法 整体 的 一 部 分 ， 你 就 明确 声明 了 ， 这 个 链接 关系 只 在 这 
个 媒体 类 型 中 定义 ， 避 免 了 在 扩展 链接 关系 类 型 中 进行 URI 命名 。 


链接 关系 还 有 一 个 有 趣 的 属性 。 链 接 可 以 指定 多 个 关系 ， 例 如 : 


<link rel="first previous" href="/foo" /> 
<link rel="nofollow noreferrer" href="/bar" /> 





请 注意 ， 这 个 功能 只 是 序列 化 的 优化 ， 但 是 的 确 允许 链接 进行 行为 组 合 。RFC 5988 规定 : 


关系 类 型 不 应 当 根 据 另 一 个 关系 类 型 存在 与 否 ， 或 者 该 关系 类 型 自身 出 现 的 次 
数 ， 来 推断 任何 附加 的 语义 。 





在 语义 上 ， 前 一 个 示例 和 下 面 的 示例 并 没有 区 别 : 

















<link rel="first" href="/foo" /> 
<link rel="previous" href="/foo" /> 


<link rel="nofollow" href="/bar" /> 
<link rel="noreferrer" href="/bar" /> 














RFC 5988 还 定义 了 链接 的 一 组 其 他 元 数据 属性 ， 可 以 为 用 户 代理 提供 信息 ， 说 明 链 接应 该 
如 何 处 理 。 这 些 信息 不 是 在 书面 文档 中 指定 ， 而 是 租 入 在 链接 的 表示 中 : 

















<link href="..." rel="related" title="More info...." hreflang="en" 
type="text/plain" > 


这 些 属性 只 是 给 用 户 代理 的 提示 信息 ， 并 不 能 保证 服务 器 会 提供 与 提示 信息 一 致 的 资源 
表示 。 


6.4.7 ”完美 结合 

链接 关系 类 型 和 媒体 类 型 就 是 分 布 式 应 用 世界 的 花生 效 和 果 效 。 链 接 关系 类 型 把 资源 表示 
绑 定 在 一 起 ， 创 造 出 完整 的 应 用 程序 ， 帮 助 用 户 实现 目标 。 当 你 把 语义 均匀 分 布 在 这 些 协 
议 类 型 上 ， 使 重用 成 为 可 能 时 ， 这 些 类 型 工作 效果 最 佳 。 


6.5 设计 新 的 媒体 类 型 协议 
在 试图 确定 用 于 某 个 资源 的 最 佳 媒 体 类 型 时 ， 你 应 该 总 是 首先 学 虑 标准 媒体 类 型 。 创 建 媒 


体 类 型 具有 挑战 性 ， 虽 然 有 时 标准 媒体 类 型 可 能 不 是 正好 符合 你 的 需求 ， 但 是 也 许 能 够 承 
载 足够 多 的 语义 信息 ， 使 客户 端 实 现 用 户 的 目标 。 
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如 果 你 确定 现 有 的 媒体 类 型 或 链接 关系 不 能 承载 所 需 的 语义 ， 那 么 也 许可 以 考虑 创建 一 个 
新 的 媒体 类 型 。 在 创建 媒体 类 型 时 ， 你 需要 设计 实现 如 下 特征 。 


。 表达 的 语义 可 以 由 一 个 以 上 应 用 程序 使 用 。 
。 要 求 最 简 的 语法 ,进行 开放 性 的 假设 。 也 就 是 说 ,信息 的 缺失 并 不 说 明 该 信息 的 任何 情况 。 
。 不 可 识别 的 信息 不 予 理会 ， 除 非 该 信息 与 其 他 规则 冲突 。 


6.5.1 选择 格式 

当 开 发 者 们 考虑 为 媒体 类 型 选择 一 个 格式 时 ， 大 多 数 时 候 会 想到 用 XML BK ISON 作为 基 
础 格式 。 选 择 XML 或 JSON 作为 基础 格式 的 好 处 是 ， 有 很 多 处 理 这 些 格式 的 工具 可 用 ， 
而 且 XML 或 JSON 为 定义 附加 语义 提供 了 灵活 的 结构 。XML 和 JSON 各 有 优 缺 点 ， 很 多 
时 候 ， 选 择 哪 个 格式 完全 是 个 人 喜好 。 但 是 ， 你 打算 支持 哪 种 客户 端 类 型 的 确 会 对 格式 选 
择 产生 影响 。 如 果 你 的 媒体 类 型 预期 的 主要 使 用 者 是 JavaScript 客户 端 ， 那 么 显然 应 该 先 
择 JSON。 而 对 于 与 大 型 企业 应 用 结合 的 系统 ，XML 可 能 更 加 合适 。 不 管 是 哪 种 情况 ， 作 
为 Web 开发 者 ， 两 种 格式 我 们 都 需要 掌握 ， 并 使 用 最 适合 需求 的 格式 。 






































但 是 ， 我 要 提醒 你 ， 同 时 使 用 XML F JSON 要 格外 谨慎 。XML 和 JSON 在 数据 表示 方法 
上 差异 很 大 ， 如 果 两 个 格式 一 起 使 用 ， 你 创建 出 的 格式 有 可 能 是 最 小 公分 母 ， 不 能 充分 发 
挥 任何 一 方 的 优点 。 如 果 你 的 确 需要 同时 支持 这 两 种 格式 ， 那 么 就 需要 认识 到 ， 管 理 两 种 
不 同 的 规范 格式 需要 双 倍 的 工作 量 ， 而 且 使 用 这 个 媒体 类 型 的 用 户 可 能 也 不 多 。 对 于 像 
HAL 这 样 的 通用 类 型 ， 支 持 XML 和 JSON 两 种 变种 可 能 还 有 意义 ， 但 是 你 应 该 谨慎 做 出 
决定 : 支持 两 个 功能 略 有 不 同 的 变种 可 能 会 产生 很 多 困惑 ， 与 其 这 样 ， 还 不 如 去 迎合 那些 
不 采用 单一 格式 的 主流 用 户 。 























有 时 ，XML 和 JSON 都 不 是 合适 的 选择 。 很 多 时 候 ， 人 们 使 用 JSON 文档 去 更 新 单个 属 
性 的 值 。 在 有 些 情 况 下 ， 纯 文本 格式 的 表示 是 最 简单 的 选择 。 所 有 的 语言 都 提供 程序 库 ， 
把 简单 文本 转换 成 本 地 数据 类 型 。 如 果 你 只 是 要 传输 一 个 简单 数值 ， 那 么 可 以 考虑 使 用 
text/plain 或 者 其 衍生 类 型 。 
































text/plain 格式 的 使 用 是 一 个 很 好 的 例子 ， 说 明了 为 什么 我 们 应 该 把 元 数据 
放 在 HTTP 表示 的 正文 之 外 。 很 多 API 把 状态 码 和 其 他 元 数据 放 在 相应 消息 
的 正文 里 。 但 是 ， 如 果 这 样 做 ， 你 能 使 用 的 媒体 类 型 就 受到 了 限制 ， 而 且 重 
复 了 HTTP 标 头 的 含义 。 如 果 你 不 得 不 支持 无 法 访问 HTTP 标 头 的 客户 端 ， 
那么 可 以 专门 为 这 些 客户 端 定 义 特 殊 的 媒体 类 型 ， 而 尽量 不 要 在 API 中 约束 
其 他 功能 更 强 的 客户 端 。 









































不 止 是 基于 文本 的 类 型 可 以 进行 创造 性 的 使 用 。 在 一 篇 博文 (http://roy.gbiv.com/ 
untangled/2008/paper-tigers-and-hidden-dragons) 中 ，Roy Fielding 演示 了 如 何 把 一 个 单 色 
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像 用 做 稀 下 数 列 ， 在 一 个 表示 中 标识 出 已 修改 的 资源 ， 从 而 避免 对 大 量 资源 进行 轮 询 。 


6.5.2 ”支持 超 媒体 

正如 第 1 章 中 介绍 的 ， 对 于 不 是 基于 文本 的 媒体 类 型 ， 超 媒体 的 最 佳 选择 是 使 用 RFC 5988 
中 定义 的 链接 标 头 。 对 于 基于 文本 的 格式 ， 我 们 在 介绍 链接 关系 时 讨论 了 各 种 现 有 的 链接 
语法 。 但 是 ， 在 媒体 类 型 层次 ， 我 们 需要 解决 一 些 其 他 的 问题 。 媒 体 类 型 应 该 允许 一 个 关 
系 有 两 个 链接 吗 ? 如 果 人 允许 ， 那 么 用 户 代 理 该 如 何 区 分 这 两 个 链接 呢 ? 在 HAL 中 ,一 个 
链接 可 以 由 相关 的 name 属性 进行 标识 。HTML 的 标签 可 以 有 相关 的 id 属性 ， 用 做 标识 。 


超 链接 需要 指向 这 个 媒体 类 型 的 一 个 实例 的 某 个 资源 吗 ? 我 们 应 该 为 标识 片段 定义 语法 吗 ? 
解析 相对 URI 的 规则 是 什么 ? 


6.5.3 可 选 、 强 制 、 省 略 和 适用 

我 发 现 ， 在 设计 媒体 类 型 时 ， 尤 其 是 用 于 表示 可 写 资源 的 媒体 类 型 时 ， 我 们 需要 传递 特定 
信息 是 否 存 在 的 语义 。 最 明显 的 情况 是 mandatory 元 素 。 在 我 们 的 Issue item 媒体 类 型 
中 ，title 属性 是 唯一 的 强制 属性 。 


对 于 非 强制 的 属性 ， 资 源 表 示 中 一 个 属性 缺失 的 原因 有 很 多 种 。 一 个 资源 可 能 出 于 性 能 
的 考虑 ， 选 择 只 包含 属性 的 一 个 子 集 ， 因 此 省 略 了 某 些 属 性 。 属 性 缺失 的 另 一 个 可 能 原因 
是 属性 不 适用 。 


适用 性 是 指 一 个 属性 的 相关 性 取决 于 资源 中 另 一 个 属性 的 值 。 例 如 : 在 员工 记录 中 ， 可 能 
有 一 个 TerminatedDate 字段 。 如 果 一 个 员工 的 状态 是 Current， 那 么 TerminatedDate 字段 
就 很 可 能 不 适用 。 数 据 库 的 表 和 类 不 能 按 单个 实体 动态 改变 结构 ， 因 此 我 们 经 常会 用 null 
值 表示 一 个 属性 不 具备 有 意义 的 值 。 糟 糕 的 是 ，null 值 也 用 于 表示 一 个 属性 还 没有 赋值 ， 
这 种 情况 和 属性 不 适用 不 是 一 回 事 。 


在 媒体 类 型 表示 中 ， 我 们 可 以 完全 省 略 与 不 适用 属性 相关 的 任何 语法 ， 只 包含 属性 的 语 
法 ， 如 果 属 性 值 还 未 定义 ， 就 设置 为 null 或 empty。 


使 用 这 种 从 资源 表示 中 移 除 不 适用 属性 的 策略 ， 可 以 简化 客户 端 代码 ， 减 少 服务 器 和 客户 
端的 耦合 。 应 用 中 经 常 有 业务 逻辑 把 控制 属性 和 受 控 属 性 关联 在 一 起 。 如 果 客 户 端 假设 一 
个 属性 的 存在 表示 这 个 属性 适用 ， 那 么 客户 端 就 不 需要 了 解 相 关 业 务 逻辑 ， 业 务 逻辑 可 以 
进行 演化 而 不 影响 客户 端 。 































































































明确 定义 的 媒体 类 型 可 以 区 分 强制 、 适 用 和 省 略 属性 ， 而 对 象 序列 化 格式 受 
到 类 可 表达 语义 的 限制 ， 这 说 明明 确定 义 的 媒体 类 型 有 具有 更 好 的 表达 能 力 。 














在 定义 只 包含 资源 子 集 属性 的 表示 时 ， 你 需要 明确 区 分 省 略 信息 和 不 适用 信息 。 属 性 组 可 
以 区 分 强制 字段 ， 有 时 也 同样 可 以 帮助 区 分 省 略 信息 和 不 适用 信息 。 











6.5.4 艇 入 元 数据 和 外 部 元 数据 
你 可 以 使 用 注解 在 资源 表示 中 包含 元 数据 ， 如 mandatory 标志 、 类 型 定义 和 范围 条 件 。 
例如 : 
<foo> 
<fooDate required="true" type="Date" minValue="2001/01/01" 


maxVaLlue="2020/12/31">2010/04/12</fooDate> 
</foo> 


使 用 这 种 方法 ， 元 数据 会 与 实际 数据 一 起 解析 ， 客 户 端 很 容易 访问 元 数据 。 但 是 ， 随 着 元 
数据 量 的 增长 ， 资 产 表 示 的 大 小 会 显著 增加 ， 而 且 元 数据 的 变更 通常 远 不 如 数据 变更 频 
繁 。 此 外 ， 同 一 个 资源 类 的 多 个 资源 通常 会 重用 同样 的 元 数据 。 


如 果 一 个 资源 包含 两 组 生命 周期 不 同 的 数据 ， 最 好 的 选择 通常 是 将 这 个 资源 分 解 为 两 个 资 
源 ， 把 生命 周期 较 短 的 资源 链接 到 生命 周期 较 长 的 资源 ， 使 缓存 层 可 以 减少 网 络 上 传输 的 
数据 量 。 

使 用 外 部 元 数据 的 一 个 挑战 在 于 ， 我 们 必须 说 明 哪 些 元 数据 适用 于 哪些 表示 数据 。 有 些 
媒体 类 型 定义 了 选择 语法 ， 可 以 指向 文档 中 的 具体 数据 片段 。 例 如 ，CSS 样式 表 使 用 
selectors (参见 http:/www.w3.org/TR/CSS2/selector.html)， 基 于 XML 的 表示 可 以 使 用 
XPath 查询 ， 定 位 文档 中 的 节点 。 





6.5.5 ”可 扩展 性 

媒体 类 型 位 于 客户 端 和 服务 器 炮 合 的 交互 点 。 媒 体 类 型 规范 的 破坏 性 变更 可 能 会 破坏 客户 
端 功能 。 如 果 我 们 确保 媒体 类 型 的 可 扩展 ， 那 么 就 可 以 适应 变化 的 需求 ， 同 时 减少 破坏 性 
变更 的 发 生 。 编 写 处 理 可 扩展 格式 的 客户 端 代 码 ， 不 能 像 编 写 普 通 客户 端 代码 那样 ， 对 格 
式 进 行 各 种 假设 ， 因 而 更 加 困难 。 但 是 ， 为 编写 更 灵活 的 解析 代码 所 做 的 努力 很 快 就 能 得 
到 回报 。 


要 获得 可 扩展 性 ， 一 种 常用 的 策略 是 忽略 未 知 内 容 。 对 于 有 文档 模式 (如 XSD 结构 定义 ) 
使 用 经 验 的 人 ， 这 种 策略 看 似 有 点 违反 常理 。 但 是 ， 使 用 这 种 策略 ， 已 有 的 解析 器 可 以 继 
续 处 理 包 含 额外 信息 的 新 版 媒体 类 型 。 我 们 的 Issue 极 简 信息 模型 ， 可 以 用 XML 进行 如 
下 表示 : 


























<Issue> 

<Title>This is a bug</Title> 

<Description>Here are the details of the bug.</Description> 
</Issue> 
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假设 我 们 编写 了 一 个 解析 器 ， 使 用 XPath 查询 Issue/Title 和 /Issue/Descripton 寻找 文档 
元 素 。 如 果 媒 体 类 型 进行 了 如 下 改进 : 

















<Issue> 
<Title>This is a bug</Title> 
<FoundBy href='http://issueapi.example.org/user/342'/> 
<Description>Here are the details of the bug.</Description> 
</Issue> 


那么 ， 现 有 的 解析 器 ， 虽 然 会 漏 掉 一 些 信 息 ， 但 还 能 够 继续 处 理 这 个 文档 。 新 版 本 中 增加 
的 信息 该 如 何 处 理 ， 很 大 程度 上 取决 于 具体 情况 。 在 有 些 情 况 下 ， 忽 略 增加 的 信息 也 无 
妨 ， 另 外 一 些 情况 下 ， 应 该 提醒 用 户 ， 说 明 有 些 信 息 未 能 处 理 。 有 些 服务 可 能 拒绝 接受 服 
务 其 无 法 理解 的 额外 信息 。 所 有 这 些 处 理 方法 都 是 可 行 的 ， 但 是 没有 必要 限制 媒体 类 型 只 
支持 一 种 情况 。 


XSD 结构 定义 经 常 带 来 的 另 一 个 约束 是 文档 元 素 的 顺序 。 除 非 属 性 的 顺序 具有 某 种 语义 影 
响 ， 否 则 媒体 类 型 规范 没有 必要 强行 安排 元 素 的 顺序 。 属 性 以 某 种 特定 顺序 出 现 ， 可 能 会 
简化 解析 逻辑 ， 提 高 性 能 ， 但 是 ， 一 旦 出 现 未 知 属 性 ， 这 些 好 处 就 微不足道 了 。 支 持 可 扩 
展 性 既 需 要 应 用 约束 ， 也 需要 避免 不 必要 的 约束 。 


逮 体 类 型 规范 应 该 尽量 使 自己 仅 受 限 于 应 用 域 的 约束 ， 而 不 要 受到 服务 实现 的 约束 。 例 
如 : 如 有 果 一 个 服务 后 台 使 用 数据 库 ， 那 么 服务 通常 会 定义 字段 长 度 。 字 段 长 度 是 服务 使 用 
的 数据 库 的 约束 。 使 用 这 个 媒体 类 型 的 其 他 应 用 实现 很 可 能 有 着 不 同 的 物理 约束 。 因 为 当 
前 实现 的 限制 ， 而 任意 规定 一 个 最 小 的 约束 ， 这 种 做 法 既 不 必要 ， 也 不 明智 。 















































JSON 数值 


关于 ISON 标准 ， 人 们 还 在 进行 着 一 场 有 趣 的 辩论 。 大 部 分 的 JSON RAP, JSON È 
档 的 数值 范围 和 JavaScript 定义 的 数值 限制 是 一 样 的 (64 位 浮 点 值 )。 但 是 ，JSON 的 
创建 者 Douglas Crockford 认为 ，JSON 应 该 独立 于 JavaScript (参见 http://www.ietf.org/ 
mail-archive/web/json/current/msg00308.html) ，JSON 文档 中 的 数值 表示 应 该 没有 限制 。 
这 是 一 种 前 上 脆性 的 观点 ， 认 识 到 JSON 很 可 能 会 比 现在 的 JavaScript 实现 存在 时 间 更 
长 。 不 可 否认 ， 这 个 决定 使 解析 器 实现 者 的 日 子 不 好 过 ， 但 是 我 相信 这 些 工 作 都 是 值 
得 的 。 











作为 一 个 基本 准则 ， 在 媒体 类 型 中 定义 约束 时 ， 我 会 问 自 己 一 个 问题 : 如 果 没 有 这 个 约 
束 ， 是 不 是 还 可 以 解析 资源 表示 ， 并 传递 同样 的 含义 。 如 果 回 答 是 肯定 的 ， 那 么 我 不 会 定 
义 这 个 约束 。 规 范 中 的 规则 越 少 ， 我 们 就 越 有 可 能 在 媒体 类 型 中 进行 扩展 ， 而 不 影响 己 有 
的 代码 。 

















6.5.6 ”注册 媒体 类 型 

为 了 让 这 个 媒体 类 型 的 “分 布 式 类 型 系统 ”发 挥 作用 ， 人 们 需要 一 个 方法 发 现存 在 哪些 
可 用 的 类 型 。 IANA 注册 表 就 是 查找 媒体 类 型 的 中 心 所 在 。 但 是 ， 我 们 必须 承认 IANA 媒 
体 类 型 注册 表 的 现状 颇 为 混乱 。 目 前 ，IANA 注册 表 由 几 个 Web 页 面 组 成 ,页面 上 是 一 
堆 链接 。 很 多 这 些 链 接 指向 的 基本 是 一 封 20 年 前 的 电子 邮件 (参见 http://www.iana.org/ 
assignments/media-types/application/atomicmail) 。 但 是 ， 这 些 条 目 至 今 仍 然 存 在 ， 说 明了 因 
特 网 上 部 署 类 型 的 持久 性 。 一 旦 一 个 新 类 型 发 布 到 因特网 上 ， 就 没有 可 靠 的 方法 能 删除 这 
个 类 型 。 这 也 是 创建 媒体 类 型 新 版 本 为 什么 会 带 来 问题 的 另 一 个 原因 ， 没 有 一 个 简便 的 方 
法 能 告诉 人 们 “不 要 再 使 用 那个 版 本 ”。 




































































IANA 的 很 多 注册 条 目 已 经 更 新 为 较 新 的 XML/XSLT/XHTML 格式 ， 更 容易 由 网 络 候 虫 发 
现 和 理解 。 但 是 ， 媒 体 类 型 注册 表 还 没有 进行 这 一 “修缮 ”"， 使 用 起 来 仍然 很 不 方便 ( 参 
JL http://roy.gbiv.com/untangled/2009/wrangling-mimetypes ) 。 





媒体 类 型 的 注册 流程 也 还 非常 原始 。 你 需要 阅读 六 个 不 同 的 RFC 规范 ， 然 后 提交 一 个 
HTML 表单 (参见 http://www.iana.org/form/media-types)。 在 提交 申请 表 之 前 ， 你 最 好 在 
特 网 上 发 布 所 提议 的 规范 ， 然 后 向 DETR 类 型 邮件 列表 (参见 http://www .ietf.org/mail- 
archive/web/ietf-types/current/maillist.html) 发 送 一 个 声明 ， 说 明 你 打算 递交 这 个 提案 。 这 
个 邮件 列表 中 的 专家 可 能 会 给 你 提供 反馈 意见 ， 帮 助 解决 提案 中 发 现 的 问题 。 请 注意 ， 这 
些 专 家 是 为 你 义务 提供 指导 ， 不 是 告诉 人 们 如 何 进行 媒体 类 型 设计 的 。 在 交流 过 程 中 ， 请 
不 要 把 大 家 的 直率 和 简洁 误 认 为 是 态度 不 友好 ! 

IANA 的 确 需要 一 些 来 自 各 方 的 压力 ， 促 进 其 改进 媒体 类 型 注册 表 和 注册 流程 。 媒 体 类 型 
注册 表 是 因特网 架构 的 核心 组 成 部 分 ， 但 是 因为 其 粗糙 的 外 表 ， 给 很 多 访问 者 留 下 了 陈旧 
废弃 的 印象 。 


6.6 设计 新 的 链接 关系 


如 果 搜 索 了 链接 关系 注册 表 (参见 http://www.iana.org/assignments/link-relations/link- 
relations.xhtml)， 但 是 没有 找到 一 个 链接 关系 ， 能 够 描述 你 要 链接 的 资源 类 型 ， 那 么 你 可 
以 选择 创建 自己 的 链接 关系 类 型 。 有 三 种 不 同 的 方式 可 以 完成 这 个 任务 : 


。 定义 一 个 新 的 标准 链接 关系 类 型 规范 ， 提 交 审 批 ; 
。 创建 一 个 “扩展 的 ”链接 关系 类 型 ， 供 自己 使 用 ， 
。 如 果 你 正在 创建 媒体 类 型 规范 ， 把 链接 规范 集成 到 媒体 类 型 规范 中 。 


6.6.1 标准 链接 关系 


创建 一 个 标准 链接 关系 的 好 处 是 ， 你 可 以 在 rel 值 中 使 用 一 个 短 名 字 。 描 述 和 注册 一 个 链 
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接 关 系 类 型 不 一 定 很 复杂 。 你 可 以 参考 licencse 链接 关系 规范 (参见 http://tools.ietf.org/ 
html/rfc4946) 的 例子 。 


有 意思 的 是 ，RFC 4946 规范 只 讨论 了 在 Atom 文档 语 境 中 使 用 License 关系 。IANA 链 
接 关系 注册 表 中 也 有 一 个 链接 ， 指 向 HTML 规范 中 关于 在 HTML 文档 中 使 用 License X 
系 的 讨论 。 另 一 个 类 似 的 例子 是 monitor 链接 关系 ， 其 规范 瞳 示 monitor 链接 只 用 于 SIP 
(Session Initiation Protocol， 会 话 初 始 协议 )。 这 些 规范 上 暗示 链接 关系 的 用 途 与 特定 媒体 类 
型 绑 定 ， 这 样 做 并 不 好 。 我 们 还 要 能 够 把 许可 信息 指派 给 HTML 和 Atom 源 以 外 的 媒体 类 
型 ， 而 且 SIP 也 不 是 监控 资源 状态 的 唯一 方法 。 








当 工 作 中 有 很 多 规定 时 ， 我 们 面临 的 一 个 挑战 就 是 ， 知 道 何 时 必须 遵守 规定 ， 何 时 可 以 打 
破 规定 。 在 前 面 提 到 的 场景 中 ， 我 相信 这 些 链 接 关 系 的 价值 并 不 限于 它们 定义 的 语 境 ， 并 
打算 在 其 他 场景 中 使 用 这 些 链 接 关 系 。 我 希望 ， 随 着 更 多 的 人 在 新 的 场景 中 使 用 这 些 链接 
关系 ， 人 们 能 够 更 好 地 认识 到 链接 关系 的 可 重用 性 ， 在 新 的 规范 中 避免 将 链接 关系 局 限于 
某 些 具体 媒体 类 型 。 


创建 新 链接 关系 的 指导 原则 和 创建 新 媒体 类 型 的 原则 非常 类 似 。 链 接 关 系 应 当 尽 可 能 的 通 
用 ， 同 时 又 提供 足够 的 语义 ， 解 决 一 个 特定 领域 的 问题 。 有 些 链 接 关 系 现在 尚未 成 为 标 
准 ， 但 是 很 有 可 能 成 为 标准 。 












































e Owner 


一 个 链接 ， 指 向 主管 当前 资源 的 资源 。 
e Home 

一 个 指向 API 入 口 或 者 根 资源 的 链接 。 
。 Like 

一 个 不 安全 链接 ， 说 明 用 户 对 一 个 资源 的 喜爱 度 。 





。 Favorite 

一 个 不 安全 链接 ， 请 求 将 资源 存储 为 用 户 的 收藏 。 
Microformats 网 站 (参见 http://microformats.org/wiki/existing-rel-values) 记录 了 很 多 其 
他 的 链接 关系 提案 ， 以 及 一 些 得 到 使 用 但 是 未 成 为 标准 的 链接 关系 。sitemap (http:// 
microformats.org/wiki/rel-sitemap) 是 个 广泛 使 用 而 有 趣 的 链接 关系 ， 描 述 了 预期 响应 的 确 
HI. sitemap 是 把 所 有 语义 放置 在 链接 关系 中 ， 但 在 媒体 类 型 中 不 包含 语义 的 例子 。 


6.6.2 ”扩展 链接 关系 
RFC 5988 定义 了 扩展 链接 关系 ， 用 于 创建 未 在 IANA 注册 的 链接 关系 。 为 了 避免 命名 冲 
突 ， 你 必须 使 用 URI 做 关系 名 。URI 利 用 域 命名 系统 确保 唯一 性 。 不 幸 的 是 ， 在 链接 关系 
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中 使 用 URI， 会 使 资源 表示 变 得 大 而 难看 。 你 可 以 使 用 CURIE (参见 http://www.w3.org/ 
TR/2007/WD-curie-20070307/) 缩写 链接 关系 ， 但 是 ，CURIE A LAR XML 命名 空间 而 
工作 方式 不 同 ， 因 此 有 的 人 不 喜欢 使 用 CURIE。 


扩展 链接 关系 非常 有 用 ,但 是 也 可 能 导致 滥用 链接 关系 。 一 旦 开发 者 意识 到 链接 关系 的 威 
力 ， 往 往 会 使 用 过 度 ， 开 始 创建 服务 相关 的 链接 关系 。 虽 然 这 样 做 短期 内 没有 问题 ， 但 是 服 
务 相关 的 链接 关系 引入 了 服务 相关 的 耦合 ， 并 非 系统 演化 和 整体 Web 生态 系统 的 最 佳 选 择 。 





6.6.3 BRAHEA 

如 果 链 接 关 系 与 媒体 类 型 的 语义 紧密 相关 ， 那 么 我 们 也 许可 以 使 链接 关系 成 为 媒体 类 型 规 
范 的 一 部 分 ， 只 在 这 个 媒体 类 型 中 使 用 。HTML 的 <FORM 标签 就 是 媒体 类 型 自身 中 定义 
的 链接 关系 的 例子 。 但 是 ，<FORM> 标签 定义 在 HTML 之 中 并 不 合理 ， 现 在 人 们 需要 在 所 
有 其 他 的 超 媒 体 类 型 中 复制 类 似 的 功能 。 如 果 <FORM 定义 为 一 个 独立 的 链接 关系 ， 那 么 其 
他 媒体 类 型 要 重用 <FORM> 会 更 加 容易 。 

















6.6.4 注册 链接 关系 
注册 链接 关系 的 流程 相当 简单 ， 在 RFC 5988 (参见 http://tools.ietf.org/html/rfc5988) 中 有 
详细 说 明 。 


+ my 之 212 
6.7 ”问题 跟踪 域 中 的 媒体 类 型 
在 第 4 章 中 ， 我 们 确定 了 几 个 不 同 的 资源 分 类 : list 资源 、item 资源 、discovery 资源 和 
search 资源 。 对 于 每 个 资源 分 类 ， 我 们 需要 确定 哪 种 媒体 类 型 最 适合 承载 所 需 的 语义 。 








同 质 API 


一 些 开发 者 往往 希望 选择 一 种 媒体 类 型 ， 在 整个 API 中 重复 使 用 。 人 们 认为 ， 只 使 用 
一 种 媒体 类 型 会 减少 客户 端 开 发 者 的 工作 。 在 很 多 时 候 ， 事 实 和 人 们 认为 的 正好 相反 。 
试图 把 一 个 相当 规模 的 API 的 所 有 语义 都 打包 在 一 个 媒体 类 型 中 ， 意 味 着 要 么 媒体 类 
型 规范 非常 复杂 ， 要 么 有 些 语 义 需 要 进行 离线 沟通 。 当 API 开始 把 链接 与 外 部 系统 集 
成 时 ， 限 制 客 户 闯 只 处 理 一 种 媒体 类 型 就 会 带 来 问题 。 如 果 客 户 端 设计 为 只 处 理 指定 
的 API 媒体 类 型 ， 那 么 可 能 很 难 支持 其 他 API 使 用 的 其 他 媒体 类 型 。 


如 果 客 户 阁 能 够 轻易 处 理 很 多 不 同 的 媒体 类 型 ， 就 可 以 鼓励 偶然 重用 ， 辅 助 系统 演化 
和 集成 。 
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6.7.1 
对 返回 


已 





支持 查询 ， 可 以 搜索 条 目的 各 种 子 集 ， 


我 们 原本 可 以 使 用 HAL 甚至 XHTML， 这 两 种 类 型 都 可 以 表示 条 目 列 表 。 但 是 ， 
coLLection+json 是 专 为 表示 列表 而 设计 的 ， 似 乎 更 加 合适 。 示 例 6-13 展示 了 如 何 使 用 


list 资 源 


条 目 列表 的 资源 ， 我 们 将 使 用 collection+json (参见 http://amundsen.com/media- 
types/collection/) 媒体 类 型 。collection+tjson 是 一 个 支持 超 媒体 的 类 型 ， 专 门 设计 用 于 支持 
条 目 列表 。 这 个 媒体 类 型 支持 将 任意 一 组 数据 与 列表 中 的 每 个 条 目 关联 。collectiontjson 
还 包含 一 个 模板 属性 ， 用 于 创建 立 列表 中 的 新 条 目 。 














collection+json 表示 一 个 问题 列表 。 


示例 6 
{ 


13: 问题 列表 示例 


"collection": { 
"href": "http://localhost:8080/Issue", 


"Links": [], 
"items": [ 
{ 
"href": "http://localhost:8080/issue/1", 
"data": [ 
{ 
"name": "Description", 
"value": "This is an issue" 
}, 
{ 
"name": "Status", 
"value": "Open" 
}, 
{ 
"name": "Title", 
"value": "An issue" 
} 
J; 
"Links": [ 
{ 
"rel": "http://webapibook.net/rels#issue-processor", 
"href": "http://localhost:8080/issueprocessor/1?action=transition" 
}, 
{ 
"rel": "http: //webapibook.net/rels#issue-processor", 
"href": "http://localhost:8080/issueprocessor/1?action=close" 
} 
] 
}, 
{ 
"href": "http://localhost:8080/issue/2", 
"data": [ 
{ 
"name": "Description", 
"value": "This is a another issue" 
}, 





"name": "Status", 
"value": "Closed" 
}; 
{ 
"name": "Title", 
"value": "Another Issue" 
} 
], 
"Links": [ 
{ 
"rel": "http: //webapibook.net/rels#issue-processor", 
"href": "http://localhost:8080/issueprocessor/2?action=transition" 
}, 
{ 
"rel": "http: //webapibook.net/rels#issue-processor", 
"href": "http://localhost:8080/issueprocessor/2?action=open" 
} 
] 
} 
]， 
"queries": [ 
{ 
"rel": "http: //webapibook.net/rels#search", 
"href": "/issue", 
"prompt": "Issue search", 
"data": [ 
{ 
"name": "SearchText", 
"prompt": "Text to match against Title and Description" 
} 
] 
} 
]， 
"template": { 
"data": [] 
} 
} 


} 


6.7.2 item 资源 


对 于 单个 癌 题 的 表示 ， 我 们 有 好 几 种 选择 。 我 们 可 以 使 用 HAL， 定 义 一 个 链接 关系 issue 





说 明 内 容 ， 也 可 以 使 用 XHTML， 定 义 一 个 语义 档 





案 ， 对 HTML 添加 问题 跟踪 域 的 语义 标 


ids 或 者 可 以 定义 一 个 新 的 媒体 类 型 ， 用 于 问题 表示 。 


问题 的 概念 非常 通用 ， 很 容易 在 其 他 服务 中 重用 ， 

















因此 为 其 创建 一 个 新 的 媒体 类 型 也 是 合 








理 的 。 问 题 跟踪 不 是 小 众 冷门 的 领域 ， 每 个 软件 开发 者 都 会 用 到 问题 跟踪 ， 很 多 客户 支持 





呼叫 中 心 也 会 使 用 。 即 便 不 同 的 实施 导致 不 能 进行 全 真 通信 ， 一 个 可 以 互 操作 的 格式 也 可 


能 会 非常 地 有 用 。 
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示例 6-14 展示 了 这 种 媒体 类 型 的 一 个 表示 样 例 。 目 前 ， 这 个 媒体 类 型 定义 为 JSON。Web 
技术 的 早期 接纳 者 可 能 更 熟悉 ISON 的 使 用 ， 如 有 果 这 个 媒体 类 型 受到 关注 ， 那 么 我 们 可 以 
定义 一 个 XML 变种 ， 扩 大 使 用 者 范围 。 


附录 己 提 供 了 这 个 媒体 类 型 的 完整 规范 。 





支持 多 种 格式 


API 问题 文档 (参见 http://tools.ietf.org/html/draft-nottingham-http-problem-04) 展示 了 
一 个 有 意思 的 方法 ， 用 于 避免 为 XML 和 JSON 格式 变种 创建 两 个 不 同 的 规范 。 在 示 
例 中 ， 核 心 规范 假定 为 JSON 格式 ， 但 是 规范 的 附录 定义 了 如 何 将 媒体 类 型 映射 到 
XML 格式 。 











示例 6-14: 问题 示例 


{ 
"ud": "2", 
"title": "An issue", 
"description": "This is an issue", 
"status": "Open", 
"Links": [ 
{ 
"rel": "self", 
"href": "http://localhost:8080/issue/1" 
}, 
{ 
"rel": "http: //webapibook.net/rels#issue-processor", 
"href": "http://localhost:8080/issueprocessor/1?action=transition", 
"action": "transition" 
}, 
{ 
"rel": "http: //webapibook.net/rels#issue-processor", 
"href": "http://localhost:8080/issueprocessor/1?action=close", 
"action": "close" 
} 
] 
} 


6.7.3 discovery 资 源 


discovery 资源 是 入 口 资源 ， 指 向 系统 提供 的 其 他 资源 。 对 于 这 种 资源 ， 我 们 将 使 用 一 个 
新 近 提 出 的 媒体 类 型 json-home (参见 http://tools.ietf.org/html/draft-nottingham-json-home- 
03)。 这 个 媒体 类 型 是 专门 设计 用 于 为 资源 动态 发 现 的 入 口 资源 提供 表示 。json-home 类 似 
Atom 服务 文档 (参见 http://tools.ietf.org/html/rfc5023#section-8)， 但 是 并 不 限于 指向 Atom 
源 。json-home 文档 可 以 包含 指向 任意 资源 的 链接 ， 并 包含 用 附加 的 元 数据 ， 用 于 发 现 如 
何 使 用 这 些 链接 。 示 例 6-15 展示 了 问题 跟踪 API 可 能 使 用 的 一 个 json-home 文档 。 











示例 6-15: 根 资源 示例 
{ 


"resources": { 
"http: //webapibook.net/rels#issue": { 
"href": "/issue/{id}", 
"hints": { 


"formats": { 
"application/json": {}, 
"application/vnd.issuet+json": {} 


} 

}, 

"http: //webapibook.net/rels#issues": { 
"href": "/issue", 
"hints": { 


"formats": { 
"“application/json": {}, 
"application/vnd.collectiontjson": {} 
} 
} 
} 


"href": "/issueprocessor/{id}{?action}", 
"hints": { 
"allow": [ 
"POST" 


6.7.4 search 资 源 


ttp://webapibook.net/rels#issue-processor": 


对 于 搜索 ， 我 们 希望 能 够 使 用 collectiont+json 的 查询 功能 。 如 果 collectiontjson 的 查询 
不 能 满足 需求 ， 我 们 会 尝试 使 用 链接 关系 的 search 和 OpenSearch (http://www.opensearch. 


org/) 定义 的 协议 。 


6.8 小结 














媒体 类 型 和 链接 关系 是 用 于 管理 分 布 式 应 用 组 件 之 间 帮 








合 的 工具 。 本 章 介绍 了 使 用 这 种 看 


合 进行 应 用 程序 语义 沟通 的 不 同方 法 。 如 果 你 了 解 了 现 有 规范 ， 并 知道 如 何以 及 何 时 创建 
新 媒体 类 型 和 链接 关系 ， 就 准备 好 开始 实际 构建 API 了 。 在 下 一 章 中 ， 我 们 将 使 用 已 经 掌 





担 的 知识 ， 开 始 编写 一 个 API 示例 。 
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空谈 不 如 实践。 


在 前 两 章 ， 你 了 解 了 问题 跟踪 系统 的 设计 ， 以 及 用 于 系统 交互 的 媒体 类 型 。 这 一 章 ， 你 将 
了 解 如 何 构建 支持 这 一 设计 的 Web API 的 基本 实现 。 我 们 的 目的 不 是 要 创建 一 个 功能 完整 
的 API， 也 不 是 要 实现 整个 设计 ， 而 是 实现 系统 的 主要 部 分 ， 在 此 之 上 才能 关 广 其 他 ， 促 
进 系 统 的 演化 。 











这 一 章 不 会 过 于 详细 地 介绍 系统 的 任何 一 个 独立 部 分 ， 而 是 关注 如 何 将 各 部 分 结合 在 一 
起 。 随 后 的 章节 将 更 为 详尽 地 介绍 ASP.NET Web API 的 每 个 不 同方 面 。 





7.1 设计 
系统 的 设计 大 体 如 下 。 


(1) 有 一 个 管理 问题 的 后 台 系统 (如 GitHub), 

(2) Issue collection 资源 从 后 台 获 取 资 源 ， 返 回 Issue+Json 或 CoLLection+Json 格式 的 响 
I. Issue collection 资源 也 可 以 通过 HTTP 的 POST 方法 创建 新 问题 。 

(3) Issue ;item 资源 包含 后 台 系 统 中 一 个 问题 的 表示 形式 。 问 题 可 以 通过 PATCH 方法 更 新 ， 
通过 DELETE 请 求 删除 。 

(4) 每 个 问题 包含 具有 如 下 rel 值 的 链接 。 








。 self: 包含 资源 自身 的 URI。 
。 open: 请 求 将 问题 状态 改 为 0pen。 
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e close; 请 求 将 问题 状态 改 为 Closed。 
e transition; 请 求 将 问题 转移 到 下 一 个 合适 的 状态 (例如: 从 Open 转 到 Closed), 


(5) 一 组 Issue Processor 资源 负责 处 理 与 问题 状态 转移 相关 的 操作 。 


MAN > 
7.2 ”获得 源 代码 
你 可 以 从 WebApiBook 库 下 载 问题 跟踪 系统 Web API 的 实现 (http://bit.ly/web-api-implement ) 
和 单元 测试 代码 ， 或 者 复制 issuetracker Æ (https://github.com/webapibook/issuetracker), %& 
出 BuildingTheApi 分 支 。 


7.3 使 用 行为 驱动 开发 构建 实现 


我 们 使 用 BDD (Behavior-Driven Development， 行 为 驱动 开发 ， 参 见 http://dannorth.net/ 
introducing-bdd/) 风格 的 验收 测试 ， 采 用 测试 驱动 方法 进行 API 的 构建 。 这 种 做 法 和 传统 
测试 驱动 开发 风格 的 主要 不 同 之 处 在 于 ， 其 焦点 是 端 到 端 场景 ， 而 不 是 具体 实现 。 使 用 验 
收 风格 的 测试 ， 你 可 以 了 解 从 初始 请 求 开 始 的 整个 端 到 端 流 程 。 

















BDD 入 门 


行为 驱动 开发 是 TDD (Test-Driven Development， 测 试 驱 动 开 发 ) 的 一 种 风格 ， 关 注 
系统 行为 的 验证 ; 而 传统 测试 驱动 开发 关注 的 是 不 同 组 件 的 实现 。 在 行为 驱动 开发 中 ， 
需求 通常 由 业务 专家 以 特定 格式 编写 ， 然 后 可 由 开发 者 执行 。 

行为 驱动 开发 有 各 种 不 同 的 形式 ， 但 是 大 多 数 都 使 用 Gherkin 语法 (参见 http://behat. 
readthedocs.org/en/v2.5/guides/1.gherkin.html) ， 或 Given-When-Then 语法 。 这 种 语法 把 
测试 分 解 为 功能 和 场景 。 一 个 功能 是 一 个 待 测试 的 组 件 。 每 个 功能 有 一 个 或 多 个 场景 ， 
敌 盖 功能 的 不 同 部 分 。 每 个 场景 再 控 步 骤 细 分 ， 每 个 步骤 都 是 一 个 Given, When 和 
Then, 以 及 And 或 But 声明 。 


Given 子 铅 设置 系统 的 初始 状态 ，When 子 负 说明 对 系统 的 操作 ，Then 子 负 对 预期 的 
行为 进行 断言 。 每 个 子 句 都 可 以 有 多 个 部 分 ， 由 And (表示 包括 ) 或 But (表示 排除 ) 
连接 在 一 起 。 


7.4 浏览 解决 方案 


打开 sre 文件 夹 下 的 WebApiBook.IssueTrackerApi.sin 文件 ， 你 将 看 到 如 下 项 目 。 














注 1: 亦 可 登录 iTuring.cn 至 本 书页 面 下 载 。 





编者 注 
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e WebApiBook.IssueTrackerApi 
包含 API 的 实现 代码 。 


e WebApiBook.IssueTrackerApi.AcceptanceTests 
包 仿 行为 驱动 开发 的 验收 测试 ， 用 于 验证 系统 的 行为 。 在 这 个 项 目 中 ， 你 将 看 到 一 个 
Features 文件 夹 ， 其 中 包含 对 应 每 个 功能 的 测试 文件 ， 每 个 文件 包含 一 个 或 多 个 测试 。 

















e WebApiBook.IssueTrackerApi.SelfHost 


包含 API 的 自 托 管 代码 。 


7.5 软件 包 和 程序 库 
在 代码 中 ， 你 会 看 到 如 下 软件 包 和 工具 ; 


e Microsoft.AspNet.WebApi.Core 
ASP.NET Web API 用 于 编写 和 托管 我 们 的 API, Core 软件 包 提供 了 所 需 的 最 小 功能 


e Microsoft.AspNet.WebApi.SelfHost 


这 个 软件 包 提 供 了 在 IS 之 外 托管 API 的 功能 。 


e Autofac.WebApi 
Autofac 用 于 依赖 和 生命 周期 管理 。 


e xunit 


XUnit 用 作 测 试 框 架 /运行 器 


e Moq 


Mog 用 于 在 测试 中 模拟 对 象 。 


e Should 
Should 程序 库 用 于 进行 Should 断言 。 


e XBehave 


XBehave 程序 库 用 于 测试 中 的 Gherkin 风格 语法 。 


e CollectionJson 


支持 CoLLection+Json 媒体 类 型 。 


7.6 BRE 


源 代 码 中 包含 了 Issue Tracker API 的 一 个 自 托管 程序 。 这 个 自 托管 程序 可 以 启动 API， 让 





e 








你 使 用 浏 览 器 或 工具 (如 Fiddler) 向 API 发 送 HTTP 请 求 。 自 托管 使 ASP.NET Web API 
易于 开发 ， 是 一 个 很 好 的 功能 。 打 开 应 用 程序 (要 使 用 管理 员 权限 ) 运行 ， 你 马上 就 会 看 
到 ， 一 个 宿主 已 经 启动 并 且 正 在 运行 ， 如 图 7-1 所 示 。 














IssueApi hosted at: http://localhost :8686/ 














7-1; BRE 





需要 注意 的 是 ， 如 果 在 Visual Studio 中 运行 自 托管 项 目 ， 你 需要 以 管理 员 身 份 运行 ， 或 者 
使 用 netsh 命令 预 留 一 个 端口 。 








使 用 Accept 标 头 值 appLication/vnd.image+json， 向 http://localhost:8080 发 送 一 个 请 求 ， 
就 可 以 得 到 如 图 7-2 所 示 的 问题 集合 。 








File Edit Rules Tools View Help GET /book 
GH Win’ Config ©) #4 Replay X~ P Go |$ Stream Hk Decode | Keep: All sessions ~ &® Any Process GA Find [E] Save | HB) 个 Æ Browse ~ & Clear Cache 


四 Result Protocol Host URL Statistics | HM Inspectors | Æ AutoResponder | 团 Composer Fiters | E] Log | = Timeline 
国 32 200 HTP locahost:8080 /ssue Headers | TextView | WebForms | HexView | Auth | Cookies | Raw | JSON | XML 

















GET /ssue HTTP/1.1 

Client 
Accept: application /vnd.issue +json 
User-Agent: Fiddler 

Transport 
Host: localhost:8080 


Get SyntaxView | Transformer Headers | TextView ImageView | HexView | WebView | Auth ‘Caching 
Cookies Raw JSON XML 


HTTP/1.1 200 OK 

Content-Length: 1424 

Content-Type: application/vnd. issue+jsonj charset-utf-8 
Server: Microsoft-HTTPAPL 

Date: Mon, 07 Oct 2013 07: a 28 GMT 





"issues": [ 
{ 


http: //webapi book. net/rels#issue-processor” 
/localhost: 8080/issueprocessor/ 13action=transition”" 
"transition 











p: //webapi book. net /re1s#issue-processor 
(localhost: 8080/issueprocessor/ /azaction=close", v 














[Find... (press Ctrl+Enter to highlight all) | Viewin Notepad 














http: //localhost:8080/issue 











图 7-2: BTS API 发 送 一 个 获取 问题 的 请 求 
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如 果 在 阅读 这 一 章 时 ， 你 想 直 接 和 运行 这 个 API， 就 请 使 用 这 个 自 托管 程序 ! 你 可 以 在 API 
中 设置 断 点 ， 单 步 执行 ， 了 解 实际 执行 了 什么 操作 。 





现在 ， 开 始 动手 实现 API | 


7.7 ”模型 和 服务 


Issue Tracker API 的 实现 依赖 于 一 组 核心 服务 和 模型 。 


7.7.1 问题 和 问题 库 

因为 这 是 一 个 问题 跟踪 项 目 ， 我 们 需要 有 地 方 存储 和 获取 问题 。 接 口 IIssueStore 
(WebApiBook.IssueTrackerA pi\Infrastructure\IIssueStore.cs) 定义 了 用 于 问题 创建 、 获 取 和 
保存 的 方法 (参加 示例 7-1) 。 请 注意 ， 所 有 的 方法 都 是 异步 的 ， 因 为 这 些 方法 可 能 受到 网 
络 IO 的 限制 ， 不 应 该 阻塞 应 用 程序 的 线程 。 














示例 7-1: IIssueStore 接口 


public interface IIssueStore 

{ 
Task<IEnumerable<Issue>> FindAsync(); 
Task<Issue> FindAsync(string issueld); 
Task<IEnumerable<Issue>> FindAsyncQuery(string searchText); 
Task UpdateAsync(Issue issue); 
Task DeleteAsync(string issueld); 
Task CreateAsync(Issue issue); 


} 
示例 7-2 中 的 Issue 类 是 一 个 数据 模型 ， 包 含 了 存储 库 中 问题 的 持久 数据 。Issue 类 只 包 
资源 状态 ， 不 包含 任何 链接 。 链 接 是 API 层级 的 关注 点 ， 因 此 是 应 用 程序 状态 ， 不 属于 应 
用 域 。 








示例 7-2: Issue 类 


public class Issue 


{ 
public string Id { get; set; } 
public string Title { get; set; } 
public string Description { get; set; } 
public IssueStatus Status { get; set; } 
} 


public enum IssueStatus {Open, Closed} 


7.7.2 IssueState 


示例 7-3 中 的 IssueState 类 (WebApiBook.IssueTrackerApi\Models\IssueState.cs) 是 一 个 状 
态 模 型 ， 设 计 用 于 表示 资源 和 应 用 程序 状态 。IssueState 可 以 在 HTTP 响应 中 以 一 种 或 多 
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种 媒体 类 型 表示 。 


示例 7-3: IssueState 类 


public class IssueState 


{ 


} 


public IssueState() 


{ 
} 


Links = new List<Link>(); 


public string Id { get; set; } 

public string Title { get; set; } 

public string Description { get; set; } 

public IssueStatus Status { get; set; } 

public IList<Link> Links { get; private set; } 


请 注意 ，IssueState 类 和 Issue 类 成 员 相 同 ， 但 多 了 一 个 链接 集合 。 你 可 以 能 奇怪 为 什么 
IssueState 不 继承 Issue 类 ， 答 案 是 为 了 更 好 地 隔离 关注 点 。 如 果 IssueState 继承 Issue 
类 ， 那 这 两 个 类 就 紧密 耦合 ，Issue 的 任何 变化 都 会 影响 IssueState。 将 关注 点 隔离 ， 系 
统 的 一 部 分 可 以 独立 于 另外 的 部 分 进行 修改 ， 符 合 我 们 对 系统 的 可 演化 性 期 望 。 


7.7.3 

















IssuesState 


示例 7-4 中 的 IssuesState 类 (WebApiBook.IssueTrackerApi\Models\IssuesState.cs) 用 于 返回 一 
个 问题 集合 ， 这 个 集合 包含 一 组 顶级 链接 。 请 注意 ， 这 个 集合 还 明确 实现 了 cotLectitonson 
程序 库 的 IReadDocument 接口 。 正 如 你 将 看 到 的 ， 如 果 客 户 端 发 送 的 请 求 的 Accpept 标 头 值 为 
application/vnd.collection+json, CollectionJsonFormatter 就 会 使 用 IReadDocument 接口 输出 


Collectton+Json 格式 的 文档 。 而 标准 格式 化 程序 会 使 用 公共 方法 。 








示例 7-4: IssuesState 类 
using CJLink = WebApiContrib.CollectionJson.Link; 


public class IssuesState : IReadDocument 


{ 


public IssuesState() 


{ 
} 


Links = new List<Link>(); 


public IEnumerable<IssueState> Issues { get; set; } 
public IList<Link> Links { get; private set; } 


Collection IReadDocument.Collection 
{ 
get 
{ 
var collection = new Collection(); // <1> 
collection.Href = Links.SingleOrDefault(l => 1.Rel == 
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IssueLinkFactory.Rels.Self).Href; // <2> 
collection.Links.Add(new CJLink {Rel="profile", 

Href = new Uri("http://webapibook.net/profile")}); // <3> 
foreach (var issue in Issues) // <4> 


{ 
var item = new Item(); // <5> 
item.Data.Add(new Data {Name="Description", 
Value=issue.Description}); // <6> 
item.Data.Add(new Data {Name = "Status", 
Value = issue.Status}); 
item.Data.Add(new Data {Name="Title", 
Value = issue.Title}); 
foreach (var link in issue.Links) // <7> 
{ 
if (link.Rel == IssueLinkFactory.Rels.Self) 
item.Href = link.Href; 
else 
{ 
item.Links.Add(new CJLink{Href = link.Href, 
Rel = Link.Rel}); 
} 
} 
collection. Items .Add(item) ; 
} 


var query = new Query { 
Rel=IssueLinkFactory.Rels.SearchQuery, 
Href = new Uri("/issue", UriKind.Relative), 
Prompt="Issue search" }; // <8> 


query.Data.Add( 
new Data() { Name = "SearchText", 
Prompt = "Text to match against Title and Description" }); 
collection.Queries.Add(query); 
return collection; // <9> 


} 
这 段 代 码 中 最 有 意思 的 逻辑 是 Collection， 这 段 逻 辑 生 成 一 个 CoLLection+Json 文档 : 


。 实例 化 一 个 新 的 Collection+Json Collection 集合 

。 设置 集合 的 href 值 。<2> 

。 给 集合 添加 一 个 指向 集合 描述 的 档案 链接 。<3> 

e 重申 IssuesState 集合 <4>， 创 建 对 应 的 Collection+Json Item 实例 <5>， 并 设置 其 
Data<6> 和 Links 值 <7>。 

。 创建 一 个 “Issue search” 查 询 ， 添 加 到 文档 的 查询 集合 中 <8>。 

。 返回 集合 <9>。 


a si> 























7.7.4 Link 


示例 7-5 中 的 Link 类 (WebApiBook.IssueTrackerApi\Models\Link.cs) 保存 之 前 介绍 
准 Rel 和 Href， 并 包含 附加 的 元 数据 ， 拉 述 与 链接 相关 的 可 选 操作 。 


示例 7-5: Link 类 


public class Link 


{ 
public string Rel { get; set; } 
public Uri Href { get; set; } 
public string Action { get; set; } 
} 


7.7.5 LinkeStateFactory 


过 的 标 


现在 系统 有 了 Issue 和 IssueState， 还 需要 有 一 个 从 Issue 获得 State 的 方法 。 示 例 7-6 
中 的 IssueStateFactory (WebApiBook. IssueTrackerApi\Infrastructure\IssueStateFactory.cs ) 


以 Issue 实例 为 输入 参数 ， 返 回 一 个 对 应 的 包含 链接 的 IssueState 实例 。 





示例 7-6: IssueStateFactory 类 


public class IssueStateFactory : IStateFactory<Issue, IssueState> // <1> 


{ 


private readonly IssueLinkFactory _links; 


public IssueStateFactory(IssueLinkFactory Links) 


{ 
_links = links; 
} 
public IssueState Create(Issue issue) 
{ 
var model = new IssueState // <2> 
{ 
Id = issue.Id, 
Title = issue.Title, 
Description = issue.Description, 
Status = Enum.GetName(typeof(IssueStatus), 
issue.Status) 
}; 
// 添加 超 媒 体 


model.Links.Add(_links.Self(issue.Id)); // <2> 
model.Links.Add(_links.Transition(issue.Id)); 


switch (issue.Status) { // <3> 
case IssueStatus.Closed: 
model.Links.Add(_links.Open(issue.Id)); 
break; 
case IssueStatus.Open: 
model.Links.Add(_links.Close(issue.Id)); 
break; 
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} 


return model; 


} 


这 段 代 码 的 工作 机 制 如 下 : 


e 这 个 工厂 类 实现 IStateFactory<Issue，IssueState> 接口 ， 调 用 者 可 以 依赖 接口 而 非 具 











WKI, BK 





此 更 容易 在 单元 测试 中 模拟 这 个 工厂 类 ， 





e Create 方法 初始 化 一 个 IssueState Kf], ill Issue 中 的 数据 <1>， 
。 之 后 的 代码 包含 业务 逻辑 ， 在 IssueState 实例 中 添加 标准 链接 ， 如 Self 和 Transition <2>, 
以 及 上 下 文 相 关 的 链接 ， 如 Open 和 Close <3>。 


7.7.6 LinkFactory 


虽然 StateFactory 包含 添加 链接 的 逻辑 ， 但 IssueLinkFactory 负责 创建 链接 对 象 自身 。 
IssueLinkFactory 为 每 个 链接 提供 强 类 型 的 访问 方法 ， 以 提高 调用 代码 的 可 读 性 和 可 维 


护 性 。 





我 们 首先 要 介绍 的 是 示例 7-7 中 的 LinkFactory 类 (WebApiBook.IssueTrackerApi\Infrastructure\ 
LinkFactory.cs) ， 其 他 的 工厂 类 都 派生 自 LinkFactory 类 。 














示例 7-7: LinkFactory 类 


public abstract class LinkFactory 


{ 


private readonly UrlHelper _urlHelper; 
private readonly string _controllerName; 
private const string DefaultApi = "DefaultApi"; 


protected LinkFactory(HttpRequestMessage request, Type controllerType) // <1> 


{ 


_urlHelper = new UrlHelper(request); // <2> 
_controllerName = GetControllerName(controllerType) ; 


} 


protected Link GetLink<TController>(string rel, object id, string action, 
string route = DefaultApi) // <3> 


{ 


var uri = GetUri(new { controller=GetControllerName( 


typeof(TController)), id, action}, route); 


return new Link {Action = action, Href = uri, Rel = rel}; 


} 


private string GetControllerName(Type controllerType) // <4> 


{ 


var name = controllerType.Name; 
return name.Substring(@, name.Length - "controller".Length).ToLower(); 
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protected Uri GetUri(object routeValues, string route = DefaultApi) // <5> 


{ 

return new Uri(_urlHelper.Link(route, routeVaLues)); 
} 
public Link Self(string id, string route = DefaultApi) // <6> 
{ 

return new Link { Rel = Rels.Self, Href = GetUri( 

new { controller = _controllerName, id = id }, route) }; 

} 
public class Rels 
{ 

public const string Self = "self"; 
} 


} 


public abstract class LinkFactory<TController> : LinkFactory // <7> 
{ 
public LinkFactory(HttpRequestMessage request) : 
base(request, typeof(TController)) { } 
} 


这 个 工厂 类 根据 路 由 值 和 一 个 默认 路 由 名 ， 生 成 URI. 


。 这 个 工厂 类 的 构造 函数 有 两 个 参数 : 一 个 参数 HttpRequestMessage <1> 用 于 构造 一 个 
UrlHelper 实例 <2>，;， 男 一 个 参数 控制 器 类 型 用 于 生成 一 个 “self” 链 接 。 

e GetLink 泛 型 方法 使 用 一 个 rel， 一 个 控制 器 以 及 其 他 参数 生成 一 个 链接 。<3> 

e GetControllerName 方法 按照 给 定 的 类 型 获取 控制 器 名 ， 由 GetLink 方法 使 用 。<4> 

。 GetUri 方法 使 用 UrlHelper 方法 ， 生 成 实际 的 URI。<5> 

。 基 类 为 指定 的 控制 器 返回 一 个 Self 链接 <6>。 派 生 工厂 类 可 以 添加 额外 的 链接 ， 随 后 
将 进行 介绍 。 


e LinkFactory<TController> 提供 更 为 便捷 的 强 类 型 使 用 方式 <7>， 不 依赖 字符 串 。 








7.7.7 IssueLinkFactory 


示例 7-8 中 的 IssueLinkFactory (WebApiBook.IssueTrackerApi\Infrastructure\IssueLink Factory.cs ) 
生成 与 问题 资源 相关 的 所 有 链接 。IssueLinkFactory 不 包含 判断 链接 是 否 应 该 在 响应 中 的 
逻辑 ， 这 部 分 由 IssueStateFactory 处 理 。 


示例 7-8: IssueLinkFactory 类 


public class IssueLinkFactory : LinkFactory<IssueController> // <1> 


{ 


private const string Prefix = "http://webapibook.net/rels#"; // <5> 


public new class Rels : LinkFactory.Rels { // <3> 
public const string IssueProcessor = Prefix + "issue-processor"; 
public const string SearchQuery = Prefix + "search"; 
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} 


public class Actions { // <4> 
public const string Open="open"; 
public const string Close="close"; 


public const string Tr 


ansition="transition"; 


public IssueLinkFactory(HttpRequestMessage request) // <2> 


} 

{ 

} 
public Link Transition(str 

{ 
return GetLink<IssuePr 
Rels.IssueProcesso 

} 


public Link Open(string id 
return GetLink<IssuePr 
Rels.IssueProcesso 


} 
public Link Close(string i 


return GetLink<IssuePr 
Rels.IssueProcesso 


} 


ing id) // <6> 


ocessorController>( 
r, id, Actions. Transition); 


) { // <7> 
ocessorController>( 
r, id, Actions.Open); 


d) { // <8> 
ocessorController>( 
r, id, Actions.Close); 


IssueLinkFactory 类 的 工作 机 制 如 下 。 


。 这 个 类 派生 自 LinkFactory<IssueController>, 


<I> 


。 构造 函数 参数 是 一 个 HttpRequestMessage 实例 ， 这 个 参数 传递 给 


给 基 类 ， 用 于 生成 路 由 。<2> 


生成 指向 IssueController 的 self 链接 。 


类 。 控 制 器 名 也 传递 


。 这 个 工厂 类 还 包含 Rels<3> 和 Actions<4> 内 部 类 ， 避 免 了 在 调用 代码 中 使 用 字符 串 。 
网 站 的 URI， 带 有 一 个 #， 以 获得 指定 的 Rel。 
。 这 个 类 还 包含 Transition<6>、0pen<7> 和 Close<8> 方 法 ,生成 用 于 改变 系统 状态 的 链接 。 





。 请 注意 ， Rel 前 级 <5> 是 指向 本 


7.8 ”验收 标准 





在 开始 编写 Web API 之 前 , 我 们 要 使 用 行为 驱动 测试 的 Gherkin 语法 ， 定 义 大 致 的 验收 


标准 。 
下 面 是 Issue Tracker API 的 测试 ， 
Update-Delete， 增 删改 查 ) 操作 。 














覆盖 了 对 问题 以 及 问题 处 理 


的 CRUD (Create-Read- 





Feature: Retrieving issues 
Scenario: Retrieving an existing issue 

Given an existing issue 
When it is retrieved 
Then a '200 OK' status is returned 
Then it is returned 
Then it should have an id 
Then it should have a title 


Then it should have a description 

Then it should have a state 

Then it should have a 'self' link 

Then it should have a 'transition' Link 


Scenario: Retrieving an open issue 
Given an existing open issue 
When it is retrieved 
Then it should have a 'close' link 


Scenario: Retrieving a closed issue 
Given an existing closed issue 
When it is retrieved 
Then it should have an 'open' link 


Scenario: Retrieving an issue that does not exist 
Given an issue does not exist 
When it is retrieved 
Then a '404 Not Found' status is returned 


Scenario: Retrieving all issues 
Given existing issues 
When all issues are retrieved 
Then a '200 OK' status is returned 
Then all issues are returned 
Then the collection should have a 'self' link 


Scenario: Retrieving all issues as Collection+Json 
Given existing issues 
When all issues are retrieved as Collection+Json 
Then a '200 OK' status is returned 
Then Collection+Json is returned 
Then the href should be set 
Then all issues are returned 
Then the search query is returned 


Scenario: Searching issues 
Given existing issues 
When issues are searched 
Then a '200 OK' status is returned 
Then the collection should have a 'self' link 
Then the matching issues are returned 


Feature: Creating issues 
Scenario: Creating a new issue 
Given a new issue 
When a POST request is made 
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Then a '201 Created' status is returned 
Then the issue should be added 
Then the response location header will be set to the resource location 


Feature: Updating issues 
Scenario: Updating an issue 
Given an existing issue 
When a PATCH request is made 
Then a '200 OK' is returned 
Then the issue should be updated 


Scenario: Updating an issue that does not exist 
Given an issue does not exist 
When a PATCH request is made 
Then a '404 Not Found' status is returned 


Feature: Deleting issues 
Scenario: Deleting an issue 
Give an existing issue 
When a DELETE request is made 
Then a '200 OK' status is returned 
Then the issue should be removed 


Scenario: Deleting an issue that does not exist 
Given an issue does not exist 
When a DELETE request is made 
Then a '404 Not Found' status is returned 


Feature: Processing issues 
Scenario: Closing an open issue 
Given an existing open issue 
When a POST request is made to the issue processor 
And the action is 'close' 
Then a '200 OK' status is returned 
Then the issue is closed 


Scenario: Transitioning an open issue 
Given an existing open issue 
When a POST request is made to the issue processor 
And the action is 'transition' 
Then a '200 OK' status is returned 
The issue is closed 


Scenario: Closing a closed issue 
Given an existing closed issue 
When a POST request is made to the issue processor 
And the action is 'close' 
Then a '400 Bad Request' status is returned 


Scenario: Opening a closed issue 
Given an existing closed issue 
When a POST request is made to the issue processor 
And the action is ‘open' 
Then a '200 OK' status is returned 
Then it is opened 
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Scenario: Transitioning a closed issue 
Given an existing closed issue 


When a POST request is made to the issue processor 


And the action is 'transition' 
Then a '200 OK' status is returned 
Then it is opened 


Scenario: Opening an open issue 
Given an existing open issue 


When a POST request is made to the issue processor 


And the action is ‘'open' 
Then a '400 Bad Request' status is returned 


Scenario: Performing an invalid action 
Given an existing issue 


When a POST request is made to the issue processor 


And the action is not valid 
Then a '400 Bad Request' status is returned 


Scenario: Opening an issue that does not exist 


Given an issue does not exist 


When a POST request is made to the issue processor 


And the action is ‘'open' 
Then a '404 Not Found' status is returned 


Scenario: Closing an issue that does not exist 


Given an issue does not exist 


When a POST request is made to the issue processor 


And the action is 'close' 
Then a '404 Not Found' status is returned 


Scenario: Transitioning an issue that does not exist 


Given an issue does not exist 


When a POST request is made to the issue processor 


And the action is 'transition' 
Then a '404 Not Found' status is returned 





在 这 一 章 之 后 的 部 分 ， 你 将 深入 了 解 获 取 、 创 建 、 更 新 和 删除 的 全 部 实现 和 所 有 测试 。 问 


题 处 理 还 有 更 多 的 测试 ， 在 这 里 无 法 全 面 介绍 。 但 是 ， 我 们 会 介绍 控制 器 IssueController 
的 测试 。 你 可 以 在 GitHub 库 找到 完整 的 实现 和 测试 代码 。 








7.9 功能: 获取 问题 


这 个 功能 包括 使 用 一 个 HTTP GET 方法 从 API 获取 一 个 或 多 个 问题 。 获 取 问 题 的 响应 中 包 
含 基于 问题 状态 动态 生成 的 超 媒 体 ， 因 此 对 应 的 测试 特别 完备 。 








请 打开 测试 文件 RetrievingIssues.cs (WebApiBook.IssueTrackerApi.AcceptanceTests/Features/ 


RetrievingIssues.cs)。 请 注意 ，RetrievingIssues 派生 


自 示 例 7-9 中 的 IssueFeature 类 ( 参 








见 IssuesFeature.cs)。 这 个 类 是 所 有 测试 的 基础 类 ， 为 API 建立 一 个 内 存 中 (in-memory) 
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的 宿主 ， 测 试 可 以 向 这 个 宿主 发 送 HTTP 请 求 。 


示例 7-9: IssueFeature 类 


public abstract class IssuesFeature 
£ 
public Mock<IIssueStore> MockIssueStore; 
public HttpResponseMessage Response; 
public IssueLinkFactory IssueLinks; 
public IssueStateFactory StateFactory; 
public IEnumerable<Issue> FakeIssues; 
public HttpRequestMessage Request { get; private set; } 
public HttpClient Client; 


public IssuesFeature() 
{ 
MockIssueStore = new Mock<IIssueStore>(); // <1> 
Request = new HttpRequestMessage(); 
Request.Headers.Accept.Add( 
new MediaTypeWithQualityHeaderVaLlue("application/vnd.issue+json")); 
IssueLinks = new IssueLinkFactory(Request) ; 
StateFactory = new IssueStateFactory(IssueLinks) ; 
FakeIssues = GetFakeIssues(); // <2> 
var config = new HttpConfiguration(); 
WebApiConfiguration.Configure( 
config, MockIssueStore.Object); 
var server = new HttpServer(config); // <3> 
Client = new HttpClient(server); // <4> 


} 


private IEnumerable<Issue> GetFakeIssues() 


{ 

var fakeIssues = new List<Issue>(); 

fakeIssues.Add(new Issue { Id = "1", Title = "An issue", 
Description = "This is an issue", 
Status = IssueStatus.Open }); 

fakeIssues.Add(new Issue { Id = "2", Title = "Another issue", 
Description = "This is another issue", 
Status = IssueStatus.Closed }); 

return fakeIssues; 


} 


IssueFeature 的 构造 函数 为 之 前 提 到 的 服务 初始 化 实例 /模拟 对 象 ， 这 些 操 作对 所 有 测试 
都 是 通用 的 : 


。 创建 一 个 HttpRequest<1>， 准 备 测 试 数据 <2>， 
。 初始 化 一 个 Httpserver， 传 入 使 用 Configure 方法 准备 的 配置 对 象 <3>; 
。 把 Client 属性 设置 为 一 个 新 的 HttpCLient 实例 ， 在 其 构造 函数 中 传 入 HttpServer <4>。 














示例 7-10 展示 了 WebApiConfiguration 类 。 





示例 7-10: WebApiConfiguration 类 


public static class WebApiConfiguration 


{ 


} 


public static void Configure(HttpConfiguration config, 
IIssueStore issueStore = null) 


{ 


} 


config.Routes.MapHttpRoute("DefaultApi", // <1> 
"{controller}/{id}", new { id = RouteParameter.Optional }); 

ConfigureFormatters(config); 

ConfigureAutofac(config, issueStore); 


private static void ConfigureFormatters(HttpConfiguration config) 


{ 


} 


config. Formatters.Add(new CollectionJsonFormatter()); // <2> 
JsonSerializerSettings settings = config.Formatters.JsonFormatter. 

SerializerSettings; // <3> 
settings.NuLlValueHandling = NullValueHandling. Ignore; 
settings.Formatting = Formatting. Indented; 
settings.ContractResolver = 

new CamelCasePropertyNamesContractResolver(); 
config.Formatters.JsonFormatter .SupportedMediaTypes.Add( 

new MediaTypeHeaderValue("application/vnd.issue+json")); 


private static void ConfigureAutofac(HttpConfiguration config, 


{ 


IIssueStore issueStore) 


var builder = new ContainerBuilder(); // <4> 
builder .RegisterApiControllers(typeof(IssueController).Assembly) ; 


if (issueStore == null) // <5> 
builder .RegisterType<InMemoryIssueStore>().As<IIssueStore>(). 
InstancePerLifetimeScope(); 
else 
builder .RegisterInstance(issueStore) ; 


builder .RegisterType<IssueStateFactory>(). // <6> 

As<IStateFactory<Issue, IssueState>>().InstancePerLifetimeScope(); 
builder .RegisterType<IssueLinkFactory>().InstancePerLifetimeScope(); 
builder .RegisterHttpRequestMessage(config); // <7> 
var container = builder.Build(); // <8> 
config.DependencyResolver = new AutofacWebApiDependencyResolver (container); 


示例 7-10 中 的 WebApiConfiguration.Configure 方法 进行 了 如 下 操作 : 


。 注册 默认 路 由 <I>; 


添加 CoLLection+Json 格式 化 程序 <2>; 
配置 默认 的 ISON 格式 化 程序 ， 使 其 忽略 空 值 ， 对 属性 使 用 骆驼 拼写 法 (camel casing), 


支持 Issue 的 媒体 类 型 <3>。 
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。 创建 一 个 Autofac ContainerBuilder， 注 册 所 有 的 控制 器 <4>; 

。 如 果 传 入 issueStore (用 于 传 入 模拟 实例 ) <5>， 则 使 用 传 入 的 实例 注册 ， 否 则 默认 使 用 
InMemoryStore, 

。 注册 其 他 服务 <6>; 

e 注入 当前 的 HttpRequestMessage 作为 依赖 <7>， 以 使 IssueLinkFactory 这 样 的 工作 类 服 
务 能 够 接受 请 求 ， 

。 创建 容器 ， 并 将 其 传 给 Autofac 依赖 关系 解析 程序 <8>。 





7.9.1 获取 一 个 问题 
第 一 组 测试 验证 单个 问题 的 获取 以 及 所 有 必要 的 数据 如 下 : 


Scenario: Retrieving an existing issue 
Given an existing issue 
When it is retrieved 
Then a '200 OK' status is returned 
Then it is returned 
Then it should have an id 
Then it should have a title 


Then it should have a description 

Then it should have a state 

Then it should have a 'self' link 

Then it should have a 'transition' link 


相关 的 测试 代码 在 示例 7-11 中 。 





示例 7-11: 获取 一 个 问题 
[Scenario] 
public void RetrievingAnIssue(IssueState issue, Issue fakeIssue) 
{ 
"Given an existing issue". 
f(() => 
{ 
fakeIssue = FakeIssues.FirstOrDefauLt(); 
MockIssueStore.Setup(i => i.FindAsync('"1")). 
Returns(Task.FromResult(fakeIssue)); // <1> 
H); 
"When it is retrieved". 
f(() => 
{ 
Request.RequestUri = _uriIssue1; // <2> 
Response = Client.SendAsync(Request).Result; // <3> 
issue = Response.Content.ReadAsAsync<IssueState>().Result; // <4> 
H; 
"Then a '200 OK' status is returned". 
f(() => Response.StatusCode.ShouldEqual(HttpStatusCode.OK)); // <5> 
"Then it is returned". 
f(() => issue.ShouldNotBeNull()); // <6> 
"Then it should have an id". 





f(() => issue.Id.ShouldEqual(fakeIssue.Id)); // <7> 
"Then it should have a title”. 
f(() => issue. Title.ShouldEqual(fakeIssue.Title)); // <8> 
"Then it should have a description". 
f(() => issue.Description.ShouldEqual(fakeIssue.Description)); // <9> 
"Then it should have a state". 
f(() => issue.Status.ShouldEqual(fakeIssue.Status)); // <10> 
"Then it should have a 'self' link". 
F(() => 
{ 
var link = issue.Links.FirstOrDefauLt(l => 1.Rel == 
IssueLinkFactory.Rels.Self); 
Link.ShouldNotBeNull(); // <11> 
Link .Href.AbsoluteUri. ShouldEqual( 
"http://localhost/issue/1"); // <12> 
}) 
"Then it should have a transition link". 
F(() => 
{ 
var link = issue.Links.FirstOrDefault(l => 
L.Rel == IssueLinkFactory.Rels.IssueProcessor && 
L.Action == IssueLinkFactory.Actions. Transition) ; 
Link.ShouldNotBeNull(); // <13> 
Link.Href.AbsoluteUri. ShouldEqual( 
"http: //lLocalhost/issueprocessor/1?action=transition"); // <14> 
}) 
} 


理解 测试 
对 于 不 熟悉 XBehave.NET 的 人 ， 这 里 使 用 的 测试 语法 可 能 有 些 令 人 困惑 。 在 XBehave 中 ， 
一 个 具体 场景 的 测试 组 织 在 一 个 类 方法 中 ， 这 个 方法 用 [Sceanrio] 属性 标记 。 每 个 方法 可 


以 有 一 个 或 多 个 参数 (如 issue 和 fakeIssue), XBehave 会 把 这 些 参数 设置 为 默认 值 ， 而 
不 是 定义 内 联 变量 。 











每 个 方法 中 有 一 个 或 多 个 待 执行 的 测试 。XBehave 允许 使 用 “free form string” 语 法 ， 直 
接 用 英语 对 测试 进行 描述 。f() 函数 是 System.String 的 一 个 扩展 方法 ， 使 用 Lambda 表 
达 式 。 测 试 中 提供 的 字符 串 只 是 为 阅读 测试 代码 和 /或 查看 结果 的 用 户 提供 的 文档 ， 对 
XBehave 自身 并 没有 意义 。 在 实践 中 ， 人 们 使 用 Gherkin 语法 书写 这 个 字符 串 ， 但 实际 上 
也 不 是 必须 的 。XBehave 只 关心 Lambda 表达 式 ， 按 照 定 义 的 顺序 依次 执行 表达 式 。 





测试 中 的 另 一 个 常见 模式 是 Should 库 的 使 用 。Should 库 引 入 了 一 组 以 Should 开头 的 扩展 
方法 ， 用 于 执行 断言 ， 提 供 的 语法 比 Assert 方法 更 加 简练 。 在 问题 获取 功能 的 测试 中 ， 
ShouldEqual 和 ShouldNotBeNull 方法 调用 都 是 使 用 的 Should 库 。 





之 前 测试 的 执行 概要 如 下 : 


。 准备 返回 一 个 问题 的 模拟 存储 库 <1>; 
。 将 请 求 URI 设置 为 问题 资源 <2>; 
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。 发 送 请 求 <3>， 从 响应 中 获取 问题 <4>， 

。 验证 状态 码 为 200 <5>; 

。 验证 获取 的 问题 不 为 空 <6>; 

。 验证 获得 的 id <7>、title <8>、description <9> 和 status <10> 与 传人 模拟 库 的 问 
题 一 致 ， 

。 验证 获得 问题 有 Self 链接 ， 链 接 指向 问题 资源 ， 

。 验证 获得 的 问题 有 Transition 链接 ， 链 接 指向 问题 处 理 资源 。 


单个 问题 的 请 求 由 IssueController 的 Get 过 载 方法 处 理 ， 如 示例 7-12 MR. 





示例 7-12: IssueController 的 Get 过 载 方法 
public async Task<HttpResponseMessage> Get(string id) 


{ 
var result = await _store.FindAsync(id); // <1> 
if (result == null) 
return Request.CreateResponse(HttpStatusCode.NotFound); // <2> 
return Request.CreateResponse(HttpStatusCode.OK, 
_stateFactory.Create(result)); // <3> 
} 





文 个 方法 查询 一 个 问题 <1>， 如 有 果 问 题 资 源 未 找到 则 返回 一 个 494 Not Found <2>， 如 果 找 
到 则 返回 单个 资源 ， 而 不 是 层次 更 高 的 文档 <3>。 


正如 你 所 看 到 的 ， 这 些 测试 实际 上 大 部 分 测试 的 不 是 控制 器 自身 ， 而 是 之 前 示例 7-6 中 的 
IssueStateFactory.Create 方法 。 





7.9.2 ”获取 未 关闭 的 和 已 关闭 的 问题 


Scenario: Retrieving an open issue 
Given an existing open issue 
When it is retrieved 
Then it should have a 'close' link 


Scenario: Retrieving a closed issue 
Given an existing closed issue 
When it is retrieved 
Then it should have an 'open' link 


这 两 个 场景 测试 代码 在 示例 7-13 和 示例 7-14 中 。 


这 一 组 测试 非常 类 似 ， 一 个 测试 检查 一 个 未 关闭 问题 的 close 链接 (示例 7-13)， 另 一 个 
测试 检查 一 个 已 关闭 问题 的 open 链接 (示例 7-14)。 





示例 7-13: 获取 一 个 未 关闭 问题 
[Scenario] 
public void RetrievingAnOpenIssue(Issue fakeIssue, IssueState issue) 





"Given an existing open issue". 
f(O => 
{ 
fakeIssue = FakeIssues.Single(i => 
i.Status == IssueStatus.Open); 
MockIssueStore.Setup(i => i.FindAsync("1")).Returns( 
Task.FromResult(fakeIssue)); // <1> 


}) 
"When it is retrieved". 
f(() => 
{ 
Request.RequestUri = _uriIssue1; // <2> 
issue = Client.SendAsync(Request).Result.Content. 
ReadAsAsync<IssueState>().Result; // <3> 
})3 
"Then it should have a 'close' action link". 
f(() => 
{ 
var link = issue.Links.FirstOrDefauLt( 
l => l.Rel == IssueLinkFactory.Rels.IssueProcessor && 
L.Action == IssueLinkFactory.Actions.Close); // <4> 
Link. ShouldNotBeNull() ; 
Link.Href.AbsoluteUri. ShouldEqual( 
"http: //lLocalhost/issueprocessor/1?action=close"); 
}) 


} 
示例 7-14: 获取 一 个 已 关闭 问题 


public void RetrievingACLosedIssue(Issue fakeIssue, IssueState issue) 
{ 
"Given an existing closed issue". 
f(O => 
{ 
fakeIssue = FakeIssues.Single(i => 
i.Status == IssueStatus.Closed); 
MockIssueStore.Setup(i => i.FindAsync("2")).Returns( 
Task.FromResult(fakeIssue)); // <1> 


P 
"When it is retrieved". 
f(() => 
{ 
Request.RequestUri = _UriIssue2; // <2> 
issue = Client.SendAsync(Request).Result.Content. 
ReadAsAsync<IssueState>().Result; // <3> 
E 
"Then it should have a 'open' action link". 
f(() => 
{ 


var link = issue.Links.FirstOrDefauLt( 
l => l.Rel == IssueLinkFactory.Rels.IssueProcessor && 
L.Action == IssueLinkFactory.Actions.Open); // <4> 
Link. ShouldNotBeNull() ; 
Link.Href.AbsoluteUri. ShouldEqual( 
"http: //lLocalhost/issueprocessor/2?action=open"); 
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})s 
} 


这 两 个 测试 的 实现 也 非常 相似 : 


已 





。 准备 模拟 问题 库 ， 返 回 适用 于 测试 的 未 关闭 问题 (id=1) 或 者 已 关闭 问题 (id=2) <1>; 
。 将 请 求 URI 设置 为 要 获取 的 资源 <2>; 

。 发 送 请 求 ， 获 取 结 果 中 的 资源 <3>; 

。 验证 相应 的 Open 或 CLose 链接 存在 <4>。 


与 之 前 的 测试 类似 ， 这 个 测试 也 是 验证 IssueStateFactory 中 的 逻辑 (参见 示例 7-15)。 这 
股 逻 辑 根 据 问题 的 状态 添加 适当 的 链接 。 


示例 7-15: IssueStateFactory Create Wik 


public IssueState Create(Issue issue) 


{ 


switch (model.Status) { 
case IssueStatus.Closed: 
model.Links.Add(_links.Open(issue.Id)); 
break; 
case IssueStatus.Open: 
model.Links.Add(_links.Close(issue.Id)); 
break; 
} 


return model; 


7.9.3 获取 不 存在 的 问题 


下 一 个 场景 验证 ， 系 统 在 资源 不 存在 时 返回 404 Not Found; 





Scenario: Retrieving an issue that does not exist 
Given an issue does not exist 
When it is retrieved 
Then a '404 Not Found' status is returned 


示例 7-16 中 展示 了 场景 测试 代码 。 
示例 7-16: 获取 一 个 不 存在 的 资源 


[Scenario] 
public void RetrievingAnIssueThatDoesNotExist() 
{ 
"Given an issue does not exist". 
f(() => MockIssueStore.Setup(i => 
i.FindAsync("1")).Returns(Task.FromResult((Issue)null))); // <1> 
"When it is retrieved". 


f(() => 





} 


Request.RequestUri = _uriIssue1; // <2> 
Response = Client.SendAsync(Request).Result; // <3> 
}) 
"Then a '404 Not Found' status is returned". 
f(() => Response. StatusCode.ShouldEqual(HttpStatusCode.NotFound)); // <4> 


测试 代码 工作 过 程 如 下 。 





。 准备 返回 一 个 空 问题 的 存储 库 <1>。 请 注意 ，Task.FromResult 扩展 用 于 快速 创建 一 个 
结果 中 包含 空 对 象 的 Task。 

。 设置 请 求 URI <2>。 

。 发 送 请 求 ， 获 取 响 应 <3>。 

。 验证 返回 状态 码 为 HttpStatusCode.NotFound <4>, 











在 IssueControLter .Get 方法 中 ， 这 个 场景 的 处 理 代码 如 示例 7-17。 





示例 7-17: IssueController.Get 方法 返回 一 个 404 
if (result == null) 


return Request.CreateResponse(HttpStatusCode.NotFound) ; 


7.9.4 获取 所 有 问题 


这 个 测试 场景 验证 可 以 正确 获取 问题 集合 


Scenario: Retrieving all issues 


Given existing issues 

When all issues are retrieved 

Then a '200 OK' status is returned 

Then all issues are returned 

Then the collection should have a 'self' link 


示例 7-18 展示 了 这 个 场景 的 测试 代码 。 
示例 7-18: 获取 所 有 问题 


private Uri _uriIssues = new Uri("http://localhost/issue"); 
private Uri _uriIssue1 = new Uri("http://localhost/issue/1"); 
private Uri _uriIssue2 = new Uri("http://localhost/issue/2"); 


[Scenario] 
public void RetrievingALLIssues(IssuesState issuesState) 


{ 


"Given existing issues". 
f(() => MockIssueStore.Setup(i => i.FindAsync()).Returns( 
Task.FromResult(FakeIssues))); // <1> 
"When all issues are retrieved". 
f(O => 
{ 


Request.RequestUri = _uriIssues; // <2> 
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Response = CLient.SendAsync(Request) .ResuLt; // <3> 
issuesState = Response.Content. 
ReadAsAsync<IssuesState>().Result; // <4> 
})3 
"Then a '200 OK' status is returned". 
f(() => Response.StatusCode.ShouldEqual(HttpStatusCode.OK)); // <5> 
"Then they are returned". 


f(() => 
{ 
issuesState.Issues.FirstOrDefault(i => i.Id == "1"). 

ShouldNotBeNull(); // <6> 
issuesState.Issues.FirstOrDefault(i => i.Id == "2"). 

ShouLdNotBeNuLL( ) ; 

P 
"Then the collection should have a 'self' link". 
f(() => 
{ 
var link = issuesState.Links.FirstOrDefault( 

l => l.Rel == IssueLinkFactory.Rels.Self); // <7> 
link.ShouldNotBeNull(); 
link.Href.AbsoluteUri.ShouldEqual("http://localhost/issue"); 

}); 


} 
这 些 测试 验证 了 一 个 发 送 到 /issue 的 请 求 返 回 的 所 有 问题 。 





。 准备 返回 伪造 问题 集合 的 模拟 存储 库 <1>。 

。 设置 指向 问题 资源 的 请 求 URI <2>。 

。 发 送 请 求 ， 获 取 响 应 <3>。 

。 读 取 响应 内 容 ， 将 其 转换 为 IssueState 实例 <4>。ReadAsAsync 方法 使 用 与 HttpContent 
实例 相关 的 格式 化 程序 ， 从 响应 内 容 生 成 一 个 对 象 。 

。 验证 返回 的 状态 是 OK <5>。 

。 验证 返回 了 正确 的 问题 <6>。 

。 验证 返回 了 Self 链接 <7>。 











在 服务 器 上 ， 问 题 资 源 由 IssueController.cs 文件 (WebApiBook.IssueTrackerApi/Controllers/ 
IssueController) 处 理 。IssueController 依赖 于 问题 库 、 问 题 状 态 工厂 以 及 问题 链接 工厂 
(参见 示例 7-19) 。 





示例 7-19: IssueController 构造 函数 


public class IssueController : ApiController 

{ 
private readonly IIssueStore _store; 
private readonly IStateFactory<Issue, IssueState> _stateFactory; 
private readonly IssueLinkFactory _linkFactory; 


public IssueController(IIssueStore store, 
IStateFactory<Issue, IssueState> stateFactory, 
IssueLinkFactory linkFactory) 
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_Store = store; 
_stateFactory = stateFactory; 
_linkFactory = linkFactory; 


} 
获取 所 有 问题 的 请 求 由 无 参数 的 Get 方法 处 理 (参见 示例 7-20) . 


示例 7-20: IssueController Get 方法 


public async Task<HttpResponseMessage> Get() 
{ 
var result = await _store.FindAsync(); // <1> 
var issuesState = new IssuesState(); // <2> 
issuesState.Issues = result.Select(i => _stateFactory.Create(i)); // <3> 
issuesState.Links.Add(new Link{ 
Href=Request.RequestUri, Rel = LinkFactory.Rels.Self}); // <4> 


return Request.CreateResponse(HttpStatusCode.OK, issuesState); // <5> 
} 


请 注意 ， 这 个 方法 带 有 修饰 符 async， 返 回 Task<HttpResponseMessage>。 在 默认 情况 下 ， 
API 控制 器 操作 都 是 同步 的 ， 因 此 ， 调 用 在 执行 时 会 阻塞 发 起 调用 的 线程 。 对 于 发 出 IO 
调用 的 操作 来 说 ， 这 可 不 是 好 事 一 一 这 会 减少 能 够 处 理 请 求 的 线程 数量 。 就 问题 控制 器 而 
言 ， 所 有 的 调用 都 要 用 到 IJO， 因 此 使 用 async 并 返回 一 个 Task 是 比较 合理 的 。 我 们 可 以 
使 用 await 关键 字 ， 等 待 大 量 使 用 IO 的 操作 结束 。 


这 段 代 码 执行 的 操作 如 下 : 














。 首先 ， 发 起 异步 调用 ， 执 行 问题 库 的 FindAysnc FYE, FRAC <>; 
。 创建 一 个 IssuesState 实例 ， 以 保存 问题 数据 <2>; 

。 为 问题 集合 中 的 每 个 问题 调用 状态 工厂 类 的 Create 方法 <3>; 

。 通过 接收 到 请 求 的 URI 添 加 Self 链接 <4>; 

。 创建 响应 ， 传 入 IssuesSate 实例 以 创建 响应 内 容 <5>。 








= 





在 前 一 段 代 码 中 ， 我 们 使 用 了 Request.CreateResponse 方法 返回 一 个 HttpResponse Message, 
你 可 能 会 间 ， 为 什么 不 直接 返回 数据 模型 呢 ? 如 果 返 回 一 个 HttpResponse Message， 客 户 
端 可 以 直接 使 用 HttpResponse 的 组 件 ， 如 状态 码 和 标 头 。 虽 然 控制 右 的 这 个 操作 现在 并 没 
有 修改 响应 标 头 ， 但 是 将 来 可 能 会 发 生 这 种 情况 。 你 还 将 看 到 ， 控 制 器 的 其 他 操作 的 确 会 
修改 响应 组 件 。 
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应 该 在 哪里 处 理 超 媒体 ? 


我 们 经 常会 碰 到 这 个 问题 : 应 该 在 系统 的 什么 地 方 实现 超 媒 体 控制 ? 超 媒 体 应 该 在 控 
制 器 中 处 理 ， 还 是 应 该 通过 管道 使 用 消息 处 理 程序 、 过 滤器 或 者 格式 化 程序 处 理 ? 这 
个 问题 并 没有 唯一 正确 的 答案 一 一 所 有 这 些 地 方 都 可 以 处 理 超 媒 休 但 是 需要 权衡 
Ai SE 

。 如 果 在 控制 器 中 处 理 链接 ， 那 么 处 理 过 程 较 为 明确 /清晰 ， 更 容易 进行 单 步调 试 ; 

。 如 果 在 管道 中 处 理 链接 ， 那 么 控制 器 行为 会 更 加 简洁 ， 包 含 逻辑 较 少 ; 

。 消息 处 理 程序 、 过 滤器 和 控制 器 可 以 很 方便 地 访问 请 求 ,使 用 请 求 信息 ， 生 成 链接 。 





在 这 本 书 中 ， 我 们 选择 在 控制 器 中 处 理 超 媒体 ， 要 么 采取 Get 方法 中 获取 多 个 问题 时 
的 处 理 方 式 ， 在 行内 生成 链接 ; 要 么 采取 Get 方法 获取 单个 问题 时 的 方式 ， 使 用 注入 
的 服务 生成 链接 。 这 么 做 的 原因 是 ， 链 接 逻 辑 对 控制 器 更 明确 | 接近。 控制 器 的 任务 
是 在 业务 域 与 HTTP 世界 之 间 进 行 转换 。 因 为 链接 是 HTTP 相关 的 关注 点 ， 因 此 在 控 
制 器 中 处 理 链接 十 分 合乎 情理 。 


虽说 如 此 ,但 其 他 的 链接 处 理 方式 也 是 可 行 的 ， 并 不 是 不 能 使 用 。 











7.9.5 获取 所 有 问题 的 CoLLection+Json 表 示 
正如 前 面 一 章 中 介绍 的 ，Collection+Json 格式 非常 适合 数据 列表 的 管理 和 查询 。 问 题 资 源 
对 返回 多 个 条 目的 资源 请 求 支持 Collection+Json 格式 的 响应 。 这 个 测试 验证 系统 可 以 返 
[a] CoLLection+Json 格式 的 响应 。 





下 一 个 测试 场景 验证 API 正确 处 理 了 返回 Collection+Json 的 请 求 : 








Scenario: Retrieving all issues as Collection+Json 
Given existing issues 
When all issues are retrieved as Collection+Json 
Then a '200 OK' status is returned 
Then Collection+Json is returned 
Then the href should be set 
Then all issues are returned 
Then the search query is returned 


示例 7-21 中 的 测试 发 送 场景 中 所 描述 的 请 求 ， 并 验证 返回 的 格式 正确 。 
示例 7-21: 获取 所 有 问题 的 Collection+Json 表示 


[Scenario] 
public void RetrievingALLIssuesAsCollectionJson(IReadDocument readDocument) 
{ 
"Given existing issues". 
f(() => MockIssueStore.Setup(i => i.FindAsync()). 
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Returns(Task.FromResult(FakeIssues))); 
"When all issues are retrieved as Collection+Json". 
f(() => 
{ 
Request.RequestUri = _uriIssues; 
Request.Headers.Accept.Clear(); // <1> 
Request.Headers.Accept.Add( 
new MediaTypeWithQualityHeaderValue( 
"application/vnd.collection+json")); 
Response = Client.SendAsync(Request) .Result; 
readDocument = Response.Content.ReadAsAsync<ReadDocument>( 
new[] {new CollectionJsonFormatter()}).Result; // <2> 
p; 
"Then a '200 OK' status is returned". 
f(() => Response.StatusCode.ShouldEqual(HttpStatusCode.0K)); // <3> 
"Then Collection+Json is returned". 
f(() => readDocument.ShouldNotBeNull()); // <4> 
"Then the href should be set". 
f(() => readDocument.Collection.Href.AbsoluteUri. ShouldEqual( 
"http://localhost/issue")); // <5> 
"Then all issues are returned" 
f(() => 
{ 
readDocument.Collection.Items.FirstOrDefault( 
i=>i.Href.AbsoluteUri=="http://localhost/issue/1"). 
ShouldNotBeNull(); // <6> 
readDocument.Collection.Items.FirstOrDefault( 
i=>i.Href.AbsoluteUri=="http://localhost/issue/2"). 
ShouldNotBeNull(); 
}) 
"Then the search query is returned". 
f(() => readDocument.Collection.Queries.SingleOrDefault( 
q => q.Rel == IssueLinkFactory.Rels.SearchQuery). 
ShouldNotBeNull()); // <7> 


} 
在 标准 的 准备 操作 之 后 ， 测 试 进行 了 如 下 操作 : 








。 将 Accept 标 头 设置 为 appLciation/vnd.coLLection+json， 并 发 送 请 求 <1>; 
。 使 用 CollectionJson 软件 包 的 ReadDocument 读 取 响应 内 容 <2>; 

。 验证 返回 的 状态 码 为 200 OK <3>; 

。 验证 返回 的 文档 不 为 空 ( 即 返回 了 有 效 的 CoLLection+Json) <4>; 

。 验证 返回 文档 的 href(self) URI 设置 正确 <5>; 

。 验证 文档 中 存在 预期 的 条 目 <6>; 

。 验证 文档 的 Queries 集合 中 存在 搜索 查询 <7>。 





在 服务 器 端 ， 系 统 调用 了 和 前 一 个 测试 同样 的 方法 一 一 即 IssueController .Get()。 但 是 ， 
为 我 们 配置 使 用 了 CoLLectionJsonFormatter， 返 回 的 IssuesState 对 象 是 通过 实现 的 
IReadDocument 接口 输出 的 (参见 示例 7-4) 。 
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7.9.6 ”搜索 问题 
这 个 测试 场景 验证 API 允许 用 户 执 行 搜索 而 且 返 回 结果 : 





io 


Scenario: Searching issues 
Given existing issues 
When issues are searched 
Then a '200 OK' status is returned 
Then the collection should have a 'self' link 
Then the matching issues are returned 


示例 7-22 展示 了 这 个 场景 的 测试 代码 。 


示例 7-22: 搜索 问题 
[Scenario] 
public void SearchingIssues(IssuesState issuesState) 
{ 
"Given existing issues". 
f(() => MockIssueStore.Setup(i => i.FindAsyncQuery("another")) 
.Returns(Task.FromResuLlt(FakeIssues.Where(i=>i.Id == "2")))); // <1> 
"When issues are searched". 
f(() => 
{ 
Request.RequestUri = new Uri(_urilIssues, "?searchtext=another"); 
Response = Client.SendAsync(Request) .Result; 
issuesState = Response.Content.ReadAsAsync<IssuesState>().Result; // <2> 
})3 
"Then a '200 OK' status is returned". 
f(() => Response. StatusCode.ShouldEqual(HttpStatusCode.0K)); // <3> 
"Then the collection should have a 'self' link". 
f(() => 
{ 
var link = issuesState.Links.FirstOrDefauLt( 
l => 1.Rel == IssueLinkFactory.Rels.Self); // <4> 
Link. ShouldNotBeNulL(); 
Link .Href.AbsoluteUri. ShouldEqual( 
"http: //Localhost/issue?searchtext=another"); 
})3 
"Then the matching issues are returned". 
f(() => 
{ 
var issue = issuesState.Issues.FirstOrDefault(); // <5> 
issue. ShouldNotBeNulL(); 
issue.Id.ShouldEqual("2"); 
H; 
} 


这 些 测试 的 工作 过 程 如 下 : 





。 设置 模拟 存储 库 ， 使 其 在 调用 FindAsyncQuery 时 返回 问题 2 <I>; 
。 在 查询 URI 后 附加 查询 字符 串 ， 发 送 请 求 ， 将 响应 内 容 读 取 为 ITssueState 实例 <2>; 
。 验证 返回 状态 码 为 200 OK <3>; 
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。 验证 集合 的 Self 链接 设置 正确 <4>; 
。 验证 返回 了 预期 的 问题 <5>。 


示例 7-23 展示 了 搜索 功能 的 实现 代码 。 


示例 7-23: IssueController 的 GetSearch 方法 


public async Task<HttpResponseMessage> GetSearch(string searchText) // <1> 
{ 
var issues = await _store.FindAsyncQuery(searchText); // <2> 
var issuesState = new IssuesState(); 
issuesState.Issues = issues.Select(i => _stateFactory.Create(i)); // <3> 
issuesState.Links.Add( new Link { 
Href = Request.RequestUri, Rel = LinkFactory.Rels.Self }); // <4> 
return Request.CreateResponse(HttpStatusCode.OK, issuesState); // <5> 


} 
这 段 代码 的 工作 方式 如 下 。 


。 方法 名 为 GetSearch <l>, ASP.NET Web API 的 选择 器 直接 将 当前 的 HTTP 方法 与 以 
同一 HTTP 方法 名 开头 的 控制 器 方法 进行 匹配 。 因 此 ，Getsearch 方法 就 会 与 HTTP 的 
GET 方法 匹配 ， 查 询 字 符 串 参数 searchtext 与 HTTP 方法 的 参数 匹配 。 

。 FindAsyncQuery 方法 获取 符合 查询 条 件 的 问题 <2>。 

。 创建 一 个 IssuesState 实例 ， 将 搜索 结果 填充 其 中 <3>。 

。 添加 一 个 Self 链接 ， 指 向 初始 请 求 <4>。 

。 返回 一 个 有 效 载荷 为 搜索 到 的 问题 的 OK 响应 <5>。 























与 获取 所 有 问题 的 请 求 类 似 ， 这 个 资源 也 支持 返回 Collection+Json 格式 的 
表示 。 





到 这 里 ， 获 取 问 题 功能 的 所 有 场景 都 介绍 完了 。 现 在 ， 接 着 讨论 创建 问题 功能 ! 


7.10 功能 : 创建 问题 


这 个 功能 包括 一 个 场景 ， 即 客户 端 使 用 HTTP POST 创建 一 个 新 间 题 : 





Scenario: Creating a new issue 
Given a new issue 
When a POST request is made 
Then the issue should be added 
Then a '201 Created' status is returned 
Then the response location header will be set to the new resource location 


示例 7-24 展示 了 这 个 场景 的 测试 代码 。 
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示例 7-24: 创建 问题 


[Scenario] 
public void CreatingANewIssue(dynamic newIssue) 


"Given a new issue". 


f(O => 
{ 
newIssue = new JObject(); 
newIssue.description = "A new issue"; 
newIssue.title = "NewIssue"; // <1> 


MockIssueStore.Setup(i => i.CreateAsync(It.IsAny<Issue>())). 
Returns<Issue>(issue=> 


{ 
issue.Id = "1"; 
return Task.FromResult(""); 
H); // <2> 
P3 
"When a POST request is made". 
f(() => 
{ 


Request.Method = HttpMethod.Post; 
Request.RequestUri = _issues; 
Request.Content = new ObjectContent<dynamic>( 
newIssue, new JsonMediaTypeFormatter()); // <3> 
Response = Client.SendAsync(Request) .Result; 
})3 
"Then the issue should be added". 
f(() => MockIssueStore.Verify(i => i.CreateAsync( 
It. IsAny<Issue>()))); // <4> 
"Then a '201 Created’ status is returned". 
f(() => Response.StatusCode.ShouldEqual(HttpStatusCode.Created)); // <5> 
"Then the response location header will be set to the resource location". 
f(() => Response.Headers.Location.AbsoluteUri. ShouldEqual( 
"http://localhost/issue/1")); // <6> 


测试 代码 的 工作 过 程 如 下 。 





。 创建 一 个 要 发 送 给 服务 器 的 新 问题 <1>。 

。 配置 模拟 存储 库 ， 设 置 问题 Id <2>， 请 注意 其 中 的 Task.FromResult 调用 。CreateAsync 
方法 预期 返回 一 个 Task。 这 是 一 种 创建 “ 假 ” 任 务 的 简单 方法 。 你 将 看 到 ， 如 果 模 拟 
存储 库 的 方法 需要 返回 一 个 Task 时 ， 别 的 测试 使 用 的 也 是 同样 的 方法 。 

。 配置 请 求 ， 设 为 其 为 P05T， 请 求 内 容 为 新 问题 <3>。 这 里 需要 注意 的 是 ， 代 码 中 没有 
使 用 静态 的 CLR 类 型 (如 Issue), ， 而 是 用 JObject 实例 (Json.NET 中 定义 ) 转换 成 
dynamic。 你 稍 后 就 将 看 到 ， 我 们 可 以 在 服务 器 上 也 使 用 类 似 的 方法 保持 无 类 型 。 

。 验证 调用 了 CreateAsync 方法 创建 问题 <4>。 





























验证 返回 的 状态 码 为 201， 与 HTTP 规范 一 致 (参见 第 1 章 ) <5>。 
验证 Location 标 头 设置 为 新 创建 资源 的 地 址 <6>。 











Web 是 无 类 型 的 


在 示例 7-24 中 ， 客 户 问 创 建 了 一 个 动态 类 型 发 送 给 服务 器 ， 而 不 是 使 用 静态 类 型 。 这 
可 能 使 得 在 座 的 很 多 人 发 问 :“ 为 什么 不 使 用 静态 类 型 呢 ? ”的 确 ，.NET 是 一 个 (大 
体 上 ) 静态 的 语言 。 但 是 ，Web 是 没有 类 型 的 。 正 如 我 们 在 第 工 章 中 介绍 的 ，Web 是 
基于 消息 的 ， 而 非 基于 类 型 。 客 户 端 发 送 给 服务 器 的 消息 使 用 一 组 已 知 的 格式 ( 即 媒 
体 类 型 ) 。 一 个 媒体 类 型 描述 了 一 个 消息 的 结构 ， 与 编程 环境 (如 NET) 中 的 静态 类 
型 不 同 。 这 种 无 类 型 的 特点 并 不 是 偶然 产生 的 ， 是 有 意 这 样 设计 的 。 


Web 没有 类 型 ， 因 而 可 以 让 尽 可 能 多 的 客户 端 和 服务 器 访问 资源 。 也 正 是 因为 无 类 型 
的 特性 ， 客 户 端 和 服务 器 可 以 独立 演化 ， 多 个 版 本 并 存 。 服 务 器 可 以 理解 所 收 到 消息 
中 的 新 元 素 ， 已 有 的 客户 端 并 不 需要 升级 。 消 息 格式 的 演化 其 至 可 以 是 破坏 性 的 ， 但 
仍然 无 需 强 制 客户 阁 升 级 。 在 强 类 型 的 世界 里 ， 由 类 型 导致 的 内 在 约束 决定 了 这 些 部 
是 不 可 能 的 。 


SOAP 服务 是 一 个 协议 将 类 型 引入 Web 的 例子 ， 带 来 了 诸多 问题 。 在 实际 应 用 中 ， 实 
现 SOAP 服 务 的 公司 最 苦恼 的 是 客户 谢 。 与 SOAP 服务 通信 需要 使 用 一 个 WSDL 文 
档 ， 描 述 操作 和 类 型 。 如 果 服 务 发 生 了 重大 的 变化 ， 这 些 变化 通常 会 导致 客户 痛 无 法 
使 用 。 解 决 的 办 法 要 么 是 升级 客户 闯 ， 要 么 是 服务 的 新 版 本 与 旧版 本 并 存 ， 而 新 客户 
5% A AGE] WSDL 才能 使 用 新 版 本 的 服务 。 

虽说 如 此 ， 但 是 我 们 并 不 是 建议 你 不 使 用 类 型 。 对 于 开发 者 ， 使 用 类 型 是 访问 API 请 
求 和 响应 的 更 合理 的 方式 ， 但 是 这 些 类 型 不 应 该 成 为 与 系统 交互 的 必要 条 件 ， 而 且 使 
用 动态 类 型 也 是 完全 合理 的 (实际 上 ， 有 时 使 用 动态 类 型 比 静 态 类 型 好 处 更 多 )。 








示例 7-25 展示 了 控制 器 内 的 实现 。 


示例 7-25: IssueController 的 Post 方法 


public async Task<HttpResponseMessage> Post(dynamic newIssue) // <1> 

{ 
var issue = new Issue { 

Title = newIssue.title, Description = newIssue.description}; // <2> 

await _store.CreateAsync(issue); // <3> 
var response = Request.CreateResponse(HttpStatusCode.Created); // <4> 
response.Headers.Location = _lLinkFactory.Self(issue.Id).Href; // <5> 
return response; // <6>. 


} 
代码 工作 方式 如 下 。 


方法 自身 命名 为 PoST， 以 匹配 HTTP 的 POST 方法 <1>。 与 测试 客户 端 一 样 ， 这 个 方法 
的 参数 是 dynamic 类 型 。 在 服务 器 上 ，Json.NET 遇 到 dynamic 会 自动 创建 一 个 JObject 
实例 。 虽 然 默 认 支 持 JSON， 我 们 也 可 以 添加 定制 的 格式 化 程序 ， 用 于 支持 其 他 的 媒体 
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类 型 ， 如 application/x-www-form-urlencoded, 
。 我 们 传人 动态 实例 的 属性 ， 创 建 一 个 新 间 题 <2>。 
。 调用 存储 库 的 CreateAsync 方法 ， 存 储 这 个 问题 <3>。 
。 创建 响应 ， 返 回 201 Created 状态 <4>。 
。 我 们 调用 _linkFactory 的 Self 方法 ， 设 置 响应 的 Location 标 头 ， 然 后 返回 响应 <6>。 


问题 创建 功能 就 介绍 完了 。 接 下 来 ， 接 着 介绍 问题 更 新 ! 


7.11 功能 : 更 新 问题 


这 个 功能 覆盖 了 使 用 HTTP 的 PATCH 更 新 问题 。 我 们 选择 PATCH 方法 ， 因 为 它 允 许 客户 端 
只 发 送 修改 现 有 资源 的 部 分 数据 。 而 PUT 方法 则 需要 完全 替换 资源 的 状态 。 





























7.11.1 更 新 一 个 问题 
这 一 场景 验证 的 是 ， 客 户 端 发 送 一 个 PATCH 请 求 时 ， 相 应 的 资源 得 到 更 新 : 


Scenario: Updating an issue 
Given an existing issue 
When a PATCH request is made 
Then a '200 OK' is returned 
Then the issue should be updated 


示例 7-26 展示 了 这 一 场景 的 测试 代码 。 


示例 7-26: IssueController 的 PATCH 方法 


[Scenario] 
public void UpdatingAnIssue(Issue fakeIssue) 
{ 
"Given an existing issue". 
f(() => 
{ 
fakeIssue = FakeIssues.FirstOrDefauLt(); 
MockIssueStore.Setup(i => i.FindAsync('"1")).Returns( 
Task.FromResult(fakeIssue)); // <1> 
MockIssueStore.Setup(i => i.UpdateAsync(It.IsAny<Issue>())). 
Returns(Task.FromResult("")); 
p; 
"When a PATCH request is made". 
f(() => 
{ 
dynamic issue = new JObject(); // <2> 
issue.description = "Updated description"; 
Request.Method = new HttpMethod("PATCH"); // <3> 
Request.RequestUri = _uriIssue1; 
Request.Content = new ObjectContent<dynamic>(issue, 
new JsonMediaTypeFormatter()); // <4> 
Response = Client.SendAsync(Request).Result; 





})3 
"Then a '200 OK' status is returned". 
f(() => Response. StatusCode.ShouldEqual(HttpStatusCode.OK)); // <5> 
"Then the issue should be updated". 
f(() => MockIssueStore.Verify(i => 
i.UpdateAsync(It.IsAny<Issue>()))); // <6> 
"Then the descripton should be updated". 
f(() => fakeIssue.Description.ShouldEqual("Updated description")); // <7> 
"Then the title should not change". 
f(() => fakeIssue.Title.ShouldEqual(title)); // <8> 


} 
测试 的 工作 过 程 如 下 。 

















F 











处 理 UpdateAsync 


。 准备 模拟 存储 库 ， 使 其 在 FindAsync 调用 时 返回 需要 更 新 的 预期 问题 ， 并 
调用 <1>。 

。 新 建 一 个 JObject 实例 ， 只 设置 需要 修改 的 描述 <2>。 

。 将 请 求 方法 设置 为 PATCH <3>。 请 注意 ， 这 里 创建 了 一 个 HttpMethod 实例 ， 传 入 的 构造 
国 数 参数 是 方法 名 。 使 用 一 个 HTTP 方法 时 , 如果 不 预 设 HttpMethod 类 的 静态 属性 (如 
GET, PUT, POST 和 DELETE) ， 就 可 以 采取 这 种 构造 方式 。 

。 使 用 已 创建 的 问题 ， 新 建 一 个 ObjectContent<dynamic> 实例 ， 将 其 赋 给 请 求 内 容 。 然 后 
发 送 请 求 <4>。 请 注意 dynamic 的 用 法 : 动态 类 型 非常 适合 PATCH 方法 ， 客 户 端 可 以 只 
发 送 需要 更 新 的 问题 属性 。 

。 验证 返回 的 状态 码 是 200 OK <5>。 

。 验证 调用 了 UpdateAsync 方法 ， 传 人 参数 是 待 更 新 的 问题 <6>。 

。 验证 问题 的 描述 已 更 新 <7>。 

。 验证 问题 的 标题 未 改变 <8>。 



































问题 更 新 的 实现 由 控制 器 中 的 Patch 方法 处 理 ， 其 代码 如 示例 7-27 所 示 。 


示例 7-27: IssueController 的 Patch 方法 


public async Task<HttpResponseMessage> Patch(string id, dynamic issueUpdate) // <1> 


{ 
var issue = await _store.FindAsync(id); // <2> 
if (issue == null) // <3> 
return Request.CreateResponse(HttpStatusCode.NotFound) ; 


foreach (JProperty prop in issueUpdate) // <4> 


{ 
if (prop.Name == "title") 
issue.Title = prop.Value.ToObject<string>(); 
else if (prop.Name == "description") 
issue.Description = prop.Value. ToObject<string>(); 
} 


await _store.UpdateAsync(issue); // <5> 
return Request.CreateResponse(HttpStatusCode.O0K); // <6> 
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代码 工作 方式 如 下 。 


。 这 个 方法 使 用 两 个 参数 <1>。 参 数 id 来 自 请 求 的 URI (在 我 们 的 例子 中 ， 值 为 http:/ 
localhosUissue/1 ) ， 参 数 issueUpdate 来 自 请 求 的 JSON 内 容 。 

。 从 存储 库 中 获取 待 更 新 的 问题 <2>。 

。 如 果 待 更 新 问题 没有 找到 ， 那 么 立即 返回 一 个 404 Not Found <3>, 

。 循环 遍历 issueUpdate 的 属性 ， 只 更 新 那些 存在 的 属性 <4>。 

。 调用 存储 库 ， 更 新 问题 <5>。 

。 返回 一 个 290 OK 状态 <6>。 








7.11.2 更 新 不 存在 的 问题 


这 个 场景 确保 ， 当 客户 端 向 一 个 缺失 或 已 删除 的 问题 发 送 一 个 PATCH 请 求 时 ， 系 统 返 回 一 
个 404 Not Found 状态 : 


Scenario: Updating an issue that does not exist 
Given an issue does not exist 
When a PATCH request is made 
Then a '404 Not Found' status is returned 


在 前 一 节 中 我 们 已 经 讨论 了 控制 器 中 的 相关 代码 ， 而 示例 7-28 中 的 测试 验证 了 代码 逻辑 正 
确 ， 运 行 无 误 | 


示例 7-28: 更 新 一 个 不 存在 的 问题 
[Scenario] 
public void UpdatingAnIssueThatDoesNotExist() 
{ 
"Given an issue does not exist". 
f(() => MockIssueStore.Setup(i => i.FindAsync("1")). 
Returns(Task.FromResult((Issue)null))); // <1> 
"When a PATCH request is made". 
f(() => 
{ 
Request.Method = new HttpMethod('"PATCH"); // <2> 
Request.RequestUri = _urilIssue1; 
Request.Content = new ObjectContent<dynamic>(new JObject(), 
new JsonMediaTypeFormatter()); // <3> 
response = Client.SendAsync(Request).Result; // <4> 
H}; 
"Then a 404 Not Found status is returned". 
f(() => response.StatusCode.ShouldEqual(HttpStatusCode.NotFound)); // <5> 
} 


测试 的 工作 过 程 如 下 : 


。 准备 模拟 存储 库 ， 使 其 在 FindAsync 调用 时 返回 一 个 空 问题 ， 
。 将 请 求 方法 设置 为 PATCH <2>; 
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将 请 求 内 容 设置 为 一 个 空 J0bject 实例 ， 请 求 内 容 是 什么 其 实 无 关 紧 要 <3>; 
。 发 送 请 求 <4>， 
验证 返回 状态 为 404 Not Found, 


到 这 里 ， 更 新 问题 部 分 就 介绍 完了 。 


7.12 功能 : 删除 问题 


这 个 功能 负责 处 理 删 除 问 题 的 HTTP DELETE 请 求 。 


7.12.1 删除 一 个 问题 
这 个 场景 验证 了 ， 当 客户 端 发 送 一 个 DELETE 请 求 时 ， 相 应 的 问题 得 到 移 除 : 


Scenario: Deleting an issue 
Give an existing issue 
When a DELETE request is made 
Then a '200 OK' status is returned 
Then the issue should be removed 














这 个 场景 的 测试 (示例 7-29) 相当 简单 ， 这 一 章 前 面 的 内 容 已 经 介绍 了 测试 中 使 用 到 的 
概念 。 
示例 7-29: 删除 一 个 问题 
[Scenario] 
public void DeletingAnIssue(Issue fakeIssue) 
{ 
"Given an existing issue". 
F(() => 
{ 
fakeIssue = FakeIssues.FirstOrDefault(); 
MockIssueStore.Setup(i => i.FindAsync("1")).Returns( 
Task.FromResult(fakeIssue)); // <1> 
MockIssueStore.Setup(i => i.DeleteAsync('"1")).Returns( 
Task. FromResult("")); 
})3 
"When a DELETE request is made". 
f(O => 
{ 
Request.RequestUri = _uriIssue; 
Request.Method = HttpMethod.Delete; // <2> 
Response = Client.SendAsync(Request).Result; // <3> 
}) 
"Then the issue should be removed". 
f(() => MockIssueStore.Verify(i => i.DeleteAsync("1"))); // <4> 
"Then a '200 OK status' is returned". 
f(() => Response. StatusCode.ShouldEqual(HttpStatusCode.0K)); // <5> 
} 
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测试 工作 过 程 如 下 : 


配置 存储 库 ， 使 其 在 FindAsync 调用 时 返回 待 删除 的 问题 ， 并 人 处理 DeleteAsync 调用 <I>; 
设置 请 求 使 用 DELETE 方法 <2>， 并 发 送 请 求 <3>; 


验证 调用 了 Dele 
验证 响应 状态 为 


teAsync 方法 ， 传 和 人 参数 为 Id <4>; 
200 OK <5>, 


示例 7-30 展示 了 控制 器 中 的 实现 代码 。 


示例 7-30: 


public async T 
{ 


IssueController 的 Delete 方法 


ask<HttpResponseMessage> Delete(string id) // <1> 


var issue = await _store.FindAsync(id); // <2> 
if (issue == null) 
return Request.CreateResponse(HttpStatusCode.NotFound); // <3> 
await _store.DeleteAsync(id); // <4> 
return Request.CreateResponse(HttpStatusCode.OK); // <5> 
} 

这 段 代 码 进行 了 如 下 工作 。 
。 方法 名 为 Delete， 以 匹配 HTTP 的 DELETE 方法 <1>。 方 法 参数 为 竺 删除 问 题 的 id。 
。 从 存储 库 获 取 所 选 id 的 问题 <2>。 
。 如 果 该 问题 不 存在 ， 那 么 返回 一 个 404 Not Found 状态 <3>。 





调用 存储 库 的 DeLeteAsync 方法 ， 删 除 指定 的 问题 <4>。 


向 客户 端 返 回 一 


一 个 200 OK <5>, 


7.12.2 ”删除 不 存在 的 问题 


这 个 场景 验证 的 是 ， 
LL 404 Not Found 状态 : 


Scenario: Dele 
Given an iss 


如 果 客 户 端 向 一 个 不 存在 的 问题 发 送 一 个 DELETE 请 求 ， 那 么 系统 返 


ting an issue that does not exist 
ue does not exist 


When a DELETE request is made 


Then a '404 





HUT 


| 我们 讨论 过 更 














示 


Not Found' status is returned 


新 一 个 不 存在 问题 的 测试 ， 示 例 7-31 中 的 测试 与 其 非常 相似 。 


例 7-31: 删除 一 个 不 存在 的 问题 


[Scenario] 


public void DeletingAnIssueThatDoesNotExist() 


{ 


"Given an 


issue does not exist". 


f(() => MockIssueStore.Setup(i => i.FindAsync("1")).Returns( 


Ta 


sk.FromResult((Issue) null))); // <1> 


回 








"When a DELETE request is made". 
F(() => 
{ 
equest.RequestUri = _urilIssue; 
Request.Method = HttpMethod.Delete; // <2> 
Response = Client.SendAsync(Request) .Result; 
IDE 
"Then a '404 Not Found' status is returned". 
f(() => Response.StatusCode.ShouldEqual(HttpStatusCode.NotFound)); // <3> 
} 


测试 工作 过 程 如 下 : 


。 设置 模拟 存储 库 ， 使 其 在 请 求 问题 时 返回 空 值 <1>; 
。 发 送 删除 资源 的 请 求 <2>; 
。 验证 返回 状态 为 404 Not Found <3>, 


7.13 功能 : 处 理 问 题 


7.13.1 测试 
正如 前 面 提 到 的 ， 这 个 功能 的 测试 讨论 超出 了 这 一 章 的 讲述 范围 。 但 是 ， 你 现在 已 经 
掌握 了 理解 相关 代码 (可 从 GitHub 下 载 : https://github.com/webapibook/issuetracker/blob/ 


BuildingTheApi/test/WebA piBook.IssueTrackerApi.AcceptanceTests/Features/ProcessingIssues. 
cs) 所 需 的 所 有 概念 。 





























将 资源 的 处 理 独 立 出 去 ， 可 以 更 好 地 隔离 API 的 实现 ， 提 高 代码 的 可 读 性 和 更 易于 维护 
性 。 采 用 这 种 设计 方式 ， 你 可 以 在 不 改动 IssueController 的 情况 下 修改 资源 处 理 的 逻辑 ， 
符合 单一 责任 原则 (Single Responsibility Principle) ， 提 高 了 系统 的 可 演化 性 。 





























7.13.2 SH 


问题 处 理 资 源 由 IssueProcessorController (代码 见 示例 7-32) 实现 。 














示例 7-32: IssueProcessorController 


public class IssueProcessorController : ApiController 


{ 


private readonly IIssueStore _issueStore; 


public IssueProcessorController(IIssueStore issueStore) 


{ 
} 


_issueStore = issueStore; // <1> 


public async Task<HttpResponseMessage> Post(string id, string action) // <2> 


{ 
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bool isValid = IsValidAction(action); // <3> 
Issue issue = null; 


if (isValid) 


{ 
issue = await _issueStore.FindAsync(id); // <4> 
if (issue == null) 
return Request.CreateResponse(HttpStatusCode.NotFound); // <5> 
if ((action == IssueLinkFactory.Actions.Open | | 
action == IssueLinkFactory.Actions.Transition) && 
issue.Status == IssueStatus.Closed) 
{ 
issue.Status = IssueStatus.Open; // <6> 
} 
else if ((action == IssueLinkFactory.Actions.Close | | 
action == IssueLinkFactory.Actions.Transition) && 
issue.Status == IssueStatus.Open) 
{ 
issue.Status = IssueStatus.Closed; // <7> 
} 
else 
isValid = false; // <8> 
} 


if (!isValid) 


return Request.CreateErrorResponse(HttpStatusCode.BadRequest, 
string.Format("Action '{0}' is invalid", action)); // <9> 


await _issueStore.UpdateAsync(issue); // <10> 
return Request.CreateResponse(HttpStatusCode.OK); // <11> 


} 

public bool IsValidAction(string action) 

{ 

return (action == IssueLinkFactory.Actions.Close || 

action == IssueLinkFactory.Actions.Open || 
action == IssueLinkFactory.Actions.Transition) ; 

} 

} 
代码 工作 方式 如 下 。 


IssueProcessorController 的 构造 国 数 参 数 为 IIssueStore， 与 IssueController 类 似 <I> 


控制 器 方法 为 post， 接受 来 自 请 求 URI 的 id 和 action <2>。 

调用 IsvalidAction 方法 ， 检 查 是 否 能 够 识别 请 求 的 操作 <3>。 

调用 FindAsync 方法 ， 获 取 问 题 <4>。 

如 果 问 题 没 有 找到 ， 那 么 立即 返回 一 个 400 Not Found <5>, 

如 果 操 作为 open 或 transition， 而 且 问 题 已 关闭 ， 那 么 打开 问题 <6>。 
如 果 操 作为 close 或 transition， 而 且 问 题 未 关闭 ， 那 么 关闭 问题 <7>。 
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。 如 果 前 两 个 条 件 都 不 满足 ， 那 么 标识 该 操作 为 对 当前 状态 无 效 <8>。 

。 如 果 操 作 无 效 ， 那 么 通过 CreateErrorResponse 返回 一 个 错误 。 我 们 使 用 这 个 方法 ， 是 
为 了 使 错误 响应 包含 有 效 负载 <9>。 

。 调用 UpdateAsync 方法 更 新 问题 <10>， 返 回 一 个 200 OK 状态 <11>。 





到 这 里 ，Issue Tracker API 就 全 部 介绍 完毕 了 | 


7.14 ”小 结 


这 一 章 的 内 容 相当 丰富 。 我 们 从 系统 的 概要 设计 一 直 讨 论 到 AP 的 详细 需求 及 其 具体 实 
现 。 在 这 一 过 程 中 ， 我 们 了 解 了 Web API 在 实践 中 需要 考虑 的 很 多 方面 ， 以 及 如 何 使 用 内 
存 托管 进行 集成 测试 。 这 些 概念 对 于 使 用 ASP.NET 构建 可 演化 的 API 非常 重要 。 现 在 我 
们 可 以 开始 讨论 有 趣 的 东西 了 ! 在 下 一 章 ， 你 将 看 到 如 何 改进 这 个 API， 了 解 使 API 可 扩 
展 的 必要 工具 (如 缓存 )。 
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改进 AP| 





付出 才 有 回报 ， 敢 于 尝试 才能 成 功 。 








在 前 一 章 中 ， 我 们 讨论 了 问题 跟踪 系统 的 初始 实现 。 有 了 这 个 完整 的 可 运行 的 实现 ， 我 们 
就 可 以 用 它 来 讨论 API 的 设计 以 及 支持 API 的 媒体 类 型 。 在 本 章 中 ， 我 们 将 试图 改进 现 有 
的 实现 ， 添 加 一 些 新 功能 ， 如 缓存 、 冲 突 检 测 和 安全 性 。 我 们 依然 会 采取 在 初始 实现 中 的 
做 法 ， 用 行为 驱动 测试 的 方式 摘 述 这 些 新 功能 的 所 有 需求 。 在 添加 这 些 新 功能 时 ， 我 们 将 
识 入 实现 的 细节 ， 阅 读 真实 代码 ， 并 介绍 其 背后 的 理论 。 随 后 的 章节 将 会 更 为 详细 地 讨论 
这 些 理论 。 


8.1 新 功能 的 验收 标准 


以 下 是 我 们 的 API 测试 场景 定义 了 问题 跟踪 系统 的 新 需求 : 
































Feature: Output Caching 
Scenario: Retrieving existing issues 
Given existing issues 
When all issues are retrieved 
Then a CacheControl header is returned 
Then a '200 OK' status is returned 
Then all issues are returned 


Scenario: Retrieving an existing issue 
Given an existing issue 
When it is retrieved 
Then a LastModified header is returned 
Then a CacheControl header is returned 
Then a '200 OK' status is returned 
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Then it is returned 
Feature: Cache revalidation 


Scenario: Retrieving an existing issue that has not changed 
Given an existing issue 
When it is retrieved with an IfModifiedSince header 
Then a CacheControl header is returned 
Then a '304 NOT MODIFIED' status is returned 
Then it is returned 


Scenario: Retrieving an existing issue that has changed 
Given an existing issue 
When it is retrieved with an IfModifiedSince header 
Then a LastModified header is returned 
Then a CacheControl header is returned 
Then a '200 OK' status is returned 
Then it is returned 


Feature: Conflict detection 


Scenario: Updating an issue with no conflicts 
Given an existing issue 
When a PATCH request is made with an IfModifiedSince header 
Then a '200 OK' is returned 
Then the issue should be updated 


Scenario: Updating an issue with conflicts 
Given an existing issue 
When a PATCH request is made with an IfModifiedSince header 
Then a '409 CONFLICT’ is returned 
Then the issue is not updated 


Feature: Change Auditing 


Scenario: Creating a new issue 
Given a new issue 
When a POST request is made with an Authorization header containing the user 
identifier 
Then a '201 Created' status is returned 
Then the issue should be added with auditing information 
Then the response location header will be set to the resource location 


Scenario: Updating an issue 
Given an existing issue 
When a PATCH request is made with an Authorization header containing the user 
identifier 
Then a '200 OK' is returned 
Then the issue should be updated with auditing information 


Feature: Tracing 
Scenario: Creating, Updating, Deleting, or Retrieving an issue 


Given an existing or new issue 
When a request is made 





When the diagnostics tracing is enabled 
Then the diagnostics tracing information is generated 


ra ry 
8.2 ”实现 输出 缓存 支持 
缓存 是 使 互联 网 可 扩展 的 基础 功能 之 一 ， 如 果 正 确实 施 ， 可 以 提供 如 下 的 优点 。 
。 降低 源 服务 器 的 负载 。 
。 减少 网 络 延迟 。 客 户 端 可 以 更 快 得 到 响应 。 
。 市 省 网 络 带 宽 。 在 请 求 到 达 源 服务 器 之 前 ,所 需 的 内 容 就 可 能 在 某 些 缓存 中 间 层 中 找到 ， 
因而 减少 网 络 跳 转 。 























在 Web API 上 正确 实现 缓存 机 制 ， 主 要 需要 两 个 步骤 : 


























(D 设置 正确 的 标 头 ， 告 诉 中 间 层 和 客户 端 〈( 例 如: 代理 、 反 向 代理 、 本 地 缓存 、 浏 览 器 
等 ) 对 响应 进行 缓存 ， 
(2) 实现 条 件 GET， 使 中 间 层 能 够 在 缓存 的 副本 过 期 后 重新 验证 生效 。 














第 (D 步 需要 使 用 Exptre 或 Cache-Control 标 头 。Expire 标 头 可 以 用 于 设置 绝对 过 期 时 
间 ， 告 诉 缓存 相关 的 表示 多 长 时 间 有 效 。 大 部 分 API 实现 使 用 这 个 标 头 说 明 客户 端 最 后 一 
次 获取 这 个 表示 的 时 间 ， 或 者 服务 器 上 文档 最 后 一 次 修改 的 时 间 。 这 个 标 头 的 值 必 须 使 用 
GTM 时 间 表 示 ， 而 不 是 本 地 时 间 一 一 例如 : Expires: Mon, 1 Aug 2013 10:30:50 GMT, 5% 
一 方面 ，Cache-Control 标 头 提供 更 为 精细 的 控制 ,说明 相对 的 过 期 时 间 ， 以 及 谁 可 以 缓 
存 数据 。 下 面 的 列表 描述 了 Cache-Control 标 头 的 常用 值 。 


























e no-store 


说 明 缓存 在 任何 情况 下 都 不 应 该 保存 数据 的 副本 。 





e private 
说 明 数据 只 供 一 个 用 户 使 用 ， 因 此 应 该 保存 在 私有 缓存 (如 浏览 器 缓存 ) 中 ， 而 不 能 保 
存在 共享 缓存 (如 代理 缓存 ) 中 。 





。 public 
说 明 数 据 可 以 在 任意 地 方 进行 缓存 。 


e no-cache 


强制 缓存 在 已 缓存 副本 过 期 后 重新 进行 验证 。 


。 max-age 
说 明 一 个 以 秒 为 单位 的 时 间 增 量 ， 表 示 一 个 缓存 副本 保持 有 效 的 最 长 时 间 (例如 : max- 
age[300] 表示 缓存 副本 将 在 请 求 发 出 300 秒 后 过 期 )。 

















e s-maxage 


等 同 于 max-age， 但 是 只 对 共享 缓存 有 效 。 


8.3 添加 输出 缓存 测试 


我 们 要 做 的 第 一 们 





F 事 就 是 添加 一 个 新 文件 OutputCaching， 用 于 所 有 与 输出 缓存 相关 的 测 





试 。 我 们 的 第 一 个 测试 是 ， 在 返回 所 有 问题 的 操作 中 加 入 输出 缓存 支持 : 


ua 











Scenario: Retrieving existing issues 
Given existing issues 


When all 


issues are retrieved 


Then a CacheControl header is returned 
Then a '200 OK' status is returned 


Then all 


issues are returned 


我 们 使 用 行为 驱动 开发 ， 将 这 个 场景 转换 成 一 个 单元 测试 (参见 示例 8-1). 
示例 8-1: 获取 带 有 缓存 标 头 的 所 有 问题 


public class 


{ 


OutputCaching : IssuesFeature 


private Uri _uriIssues = new Uri("http://localhost/issue"); 


[Scenario] 


public void RetrievingALlIssues() 


{ 


IssuesState issuesState = null; 


"Given existing issues". 


f(() => 
{ 


MockIssueStore.Setup(i => i.FindAsync()) 
.Returns(Task.FromResuLt(FakeIssues) ) 


p); 
"When all issues are retrieved". 
f(() => 
{ 
Request.RequestUri = _uriIssues; 


Response = Client.SendAsync(Request) .Result; 
issuesState = Response.Content 
.ReadAsAsync<IssuesState>() 


.Result; 
p); 
"Then a CacheControl header is returned". 
f(() => 
{ 


Response.Headers.CacheControl.Public 
.ShouldBeTrue(); // <1> 
Response.Headers.CacheControl.MaxAge 
. ShouldEqual(TimeSpan.FromMinutes(5)); // <2> 


Ps 


"Then a 


1 


200 OK' status is returned". 
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f(() => Response.StatusCode.ShouldEqual(HttpStatusCode.0K)); 
"Then they are returned". 


f(O => 
{ 
issuesState. Issues 
.FirstOrDefault(i => i.Id == "1") 
. ShouLdNotBeNull(); 
issuesState. Issues 
.FirstOrDefault(i => i.Id == "2") 
. ShouLdNotBeNulL() ; 
}); 
} 
} 


这 个 单元 测试 是 自 解释 的 ， 不 用 多 加 说 明 。 关 键 代码 在 <1> 和 <2>， 进 行 CacheControl 和 
MaxAge 断言 的 地 方 。 要 使 这 个 测试 通过 ，IssueController 类 的 Get 方法 所 返回 的 响应 消息 
需要 进行 修改 ， 包 含 CacheControl 和 MaxAge 标 头 (参见 示例 8-2)。 


示例 8-2: Get 方法 的 新 版 本 
public async Task<HttpResponseMessage> Get() 


{ 
var result = await _store.FindAsync(); 
var issuesState = new IssuesState(); 
issuesState.Issues = result.Select(i => _stateFactory.Create(i)); 








var response = Request.CreateResponse(HttpStatusCode.OK, issuesState); 


response.Headers.CacheControl = new CacheControlHeaderValue(); 
response.Headers.CacheControl.Public = true; // <1> 
response.Headers.CacheControl.MaxAge = TimeSpan.FromMinutes(5); // <2> 


return response; 


} 


CacheControl 标 头 值 设置 为 Public <1>， 因 此 这 个 响应 可 以 在 任何 地 方 缓 存 ，MaxAge 标 头 
设置 为 5 分 钟 的 相对 过 期 时 间 <2>。 





示例 8-3 中 展示 的 下 一 个 场景 ， 是 为 获取 单个 问题 的 操作 添加 输出 缓存 : 





Scenario: Retrieving an existing issue 
Given an existing issue 

When it is retrieved 

Then a LastModified header is returned 
Then a CacheControl header is returned 
Then a '200 OK' status is returned 
Then it is returned 


示例 8-3: 获取 带 有 缓存 标 头 的 单个 问题 
public class OutputCaching : IssuesFeature 


{ 


private Uri _uriIssue1 = new Uri("http://localhost/issue/1"); 
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[Scenario] 
public void RetrievingAnIssue() 


{ 


IssueState issue = null; 


var fakeIssue = FakeIssues.FirstOrDefault(); 
"Given an existing issue". 
f(() => MockIssueStore 
.Setup(i => i.FindAsync("1")) 
.Returns(Task.FromResult(fakeIssue))); 
"When it is retrieved". 
F(() => 
{ 
Request.RequestUri = _urilIssue1; 
Response = Client.SendAsync(Request) .Result; 
issue = Response.Content.ReadAsAsync<IssueState>().ResuLlt; 


H; 

"Then a LastModified header is returned". 
f(() => 
{ 


Response.Content.Headers.LastModified 
.ShouldEqual(new DateTimeOffset(new DateTime(2013, 9, 4))); // <1> 


1)3 

"Then a CacheControl header is returned". 
F(() => 
{ 


Response.Headers.CacheControl.Public 
.ShouldBeTrue(); // <2> 
Response.Headers.CacheControl.MaxAge 
. ShouldEqual(TimeSpan.FromMinutes(5)); // <3> 
}); 
"Then a '200 OK' status is returned". 
f(() => Response. StatusCode.ShouldEqual(HttpStatusCode.OK)); 
"Then it is returned". 
f(() => issue.ShouldNotBeNull()); 
} 
} 
示例 8-3 PAWN, SAMA S AAR ATA aA WTR A AS Te. BR SRI AL, 
EPIRA FM LastModified R% <l>, LastModified 标 头 稍 后 将 在 其 他 场景 
用 于 缓存 重 验证 。 这 个 测试 中 CacheControl <2> 和 MaxAge <3> 标 头 的 预期 值 也 分 别 为 
Pubilc 和 5 分 钟 。 


8.4 实现 缓存 重 验证 


一 且 已 缓存 的 资源 表示 副本 变 得 陈旧 ， 缓 存 中 间 层 可 以 向 源 服 务 器 发 送 一 个 条 件 GET, E 
新 验证 这 个 副本 。 条 件 GET 用 到 两 个 响应 标 头 : If-None-Match 和 If-Modified-Since, If- 
None-Match 对 应 一 个 Etag 标 头 。Etag 是 一 个 不 透明 的 值 ， 只 有 服务 器 才 知 道 如 何 重新 创 
建 。 这 个 Etag 值 可 以 代表 任何 东西 ， te 第 是 代表 资源 版 本 的 一 个 散 列 值 ， 可 以 通过 
对 整个 表示 的 内 容 进 行 散 列 运 算 ， 或 者 只 对 一 部 分 内 容 ， 如 时 间 惟 进行 运算 得 到 。 另 一 方 
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Aj, If -Modified-Since 对 应 一 个 Last-Modified 标 头 。Last-Modified 是 一 个 时 间 值 ,服务 器 
可 以 用 这 个 时 间 来 判断 自 上 一 次 提供 资源 后 ， 这 个 资源 是 否 发 生 了 变化 。 











示例 8-4 演示 了 客户 端 /服务 器 如 何 使 用 前 面 介绍 的 这 些 缓存 标 头 进行 请 求 /响应 消息 
交换 。 


示例 8-4: 使 用 缓存 标 头 的 一 对 请 求 和 响应 消息 
Response -> 
Connection close 
Date Thu, 02 Oct 2013 14:46:57 GMT 
Expires Sat, 01 Nov 2013 14:46:57 GMT 
Last-Modified Mon, 29 Sep 2013 15:40:27 GMT 


Etag a9331828c518ac6d97f93b3cfdbcc9bc 
Content-Type application/json 


Request -> 


Host localhost 

Accept */* 

If-Modified-Since Mon, 29 Sep 2013 15:40:27 GMT 
If-None-Match a9331828c518ac6d97f93b3cfdbcc9bc 


缓存 中 间 层 可 以 使 用 If -None-Match 和 If-Modified-Since 中 的 任意 一 个 ， 判 断 源 服务 器 
上 的 资源 表示 是 否 已 发 生变 化 。 如 果 根 据 这 些 标 头 中 的 数值 ， 资 源 没 有 发 生变 化 〈If- 
Modified-Since 对 应 Last-Modified, If-None-Match 对 应 ETag) ,服务 就 会 返回 一 个 HTTP $ 
ANG 304 Not Modified， 告 诉 中 间 层 继续 保留 已 缓存 的 版 本 ， 并 刷新 过 期 时 间 。 示 例 8-4 展 
示 了 两 个 标 头 ， 但 是 在 实际 应 用 中 ， 中 间 层 只 使 用 其 中 一 个 。 


8.5 为 缓存 重 验证 实现 条 件 GET 


示例 8-5 展示 了 我 们 的 第 一 个 测试 ， 这 个 测试 会 重新 验证 已 缓存 的 一 个 问题 资源 表示 ， 这 
个 问题 在 服务 器 上 并 未 修改 。 这 些 测试 方法 位 于 Cachevalidation 类 中 。 























Scenario: Retrieving an existing issue that has not changed 
Given an existing issue 
When it is retrieved with an IfModifiedSince header 
Then a CacheControl header is returned 
Then a '304 Not Modified' status is returned 
Then it is not returned 


示例 8-5: 验证 未 改变 的 缓存 副本 的 单元 测试 
private Uri _uriIssue1 = new Uri("http://localhost/issue/1"); 


[Scenario] 
public void RetrievingNonModifiedIssue( ) 





IssueState issue = null; 


var fakeIssue = FakeIssues.FirstOrDefault(); 
"Given an existing issue". 
f(() => MockIssueStore.Setup(i => i.FindAsync("1")) 
.Returns(Task.FromResult(fakeIssue))); 
"When it is retrieved with an IfModifiedSince header". 


f(() => 
{ 


Request.RequestUri = _uriIssue1; 
Request .Headers.IfModifiedSince = fakeIssue.LastModified; // <1> 
Response = Client.SendAsync(Request) .Result; 


3 

"Then a CacheControl header is returned". 
F(() => 
{ 


Response.Headers.CacheControl.Public.ShouldBeTrue(); 


Response.Headers.CacheControl.MaxAge.ShouldEqual(TimeSpan.FromMinutes(5)); 


p; 
"Then a '304 NOT MODIFIED' status is returned". 


f(() => Response.StatusCode.ShouldEqual(HttpStatusCode.NotModified)); // <2> 


"Then it is not returned". 
f(() => Assert.Null(issue)); 
} 


示例 8-5 展示 了 一 个 单元 测试 ， 在 这 个 测试 验证 的 场景 中 ， 源 服务 器 上 的 资源 表示 自 








缓存 之 后 没有 发 生 改 变 。 这 个 测试 模拟 了 一 个 缓存 中 间 层 的 行为 ， 使 用 预先 保存 的 
IfModifiedsince 标 头 值 <1>， 向 服务 器 发 送 一 个 条 件 GET。 在 预期 验证 部 分 ， 啊 应 的 状态 








码 预 期 值 为 304 NOT MODIFIED <2>。 


我 们 需要 修改 IssueController 类 的 Get 方法 ， 加 入 所 有 的 条 件 GET 逻辑 (参见 示例 8-6)。 
如 果 服 务 收 到 一 个 带 有 IfModifiedsince 标 头 的 请 求 消息 ,那么 应 该 将 标 头 中 的 日 期 值 , 与 
受到 请 求 的 问题 的 LastModified 字段 进行 比较 ， 判 断 这 个 问题 在 最 后 一 次 发 送 给 缓存 中 间 





层 之 后 ， 是 否 发 生 了 改变 。 
示例 8-6: 支持 条 件 GET 的 新 版 本 Get 方法 


public async Task<HttpResponseMessage> Get(string id) 


{ 


var result = await _store.FindAsync(id); 
if (result == null) 
return Request.CreateResponse(HttpStatusCode.NotFound) ; 


HttpResponseMessage response = null; 


if( Request.Headers.IfModifiedSince.HasValue && 
Request.Headers.IfModifiedSince == result.LastModified) // <1> 
{ 
response = Request 
. CreateResponse(HttpStatusCode.NotModified); // <2> 
} 


else 





改进 API 


171 


{ 


response = Request 


.CreateResponse(HttpStatusCode.0K, _stateFactory.Create(result)); 


response.Content.Headers.LastModified = result.LastModified; 


} 


response.Headers.CacheControl = new CacheControlHeaderValue(); // <3> 


response.Headers.CacheControl.Public = true; 


response.Headers.CacheControl.MaxAge = TimeSpan.FromMinutes(5); 


return response; 


} 


示例 8-6 中 的 新 代码 检查 请 求 中 是 否 包含 IfModifiedsince 标 头 ， 以 及 标 头 值 是 否 与 获取 的 


问题 的 LastModified 字段 值 相 等 <1>。 如 果 这 些 条 件 都 满足 ， 那 么 服务 返回 








一 个 状态 码 为 


304 Not Modified 的 响应 <2>。 代 码 的 最 后 更 新 缓存 标 头 值 , 并 将 缓存 标 头 作为 响应 的 一 部 
分 返回 <3>。 


在 我 们 下 一 个 测试 (参见 示例 8-7) 场景 





缓存 后 ， 发 生 了 改变 : 


Scenario: Retrieving an existing issue that has changed 
Given an existing issue 
When it is retrieved with an IfModifiedSince header 
Then a LastModified header is returned 
Then a CacheControl header is returned 
Then a '200 OK' status is returned 
Then it is returned 


示例 8-7: 验证 已 改变 的 缓存 副本 的 单元 测试 


private Uri _uriIssuel = new Uri("http://localhost/issue/1"); 


[Scenario] 
public void RetrievingModifiedIssue() 


{ 


IssueState issue = null; 
var fakeIssue = FakeIssues.FirstOrDefault(); 


"Given an existing issue". 
f(() => MockIssueStore.Setup(i => i.FindAsync("1")) 
.Returns(Task.FromResult(fakeIssue) )); 
"When it is retrieved with an IfModifiedSince header". 
F(() => 
{ 
Request.RequestUri = _uriIssue1; 
Request .Headers.IfModifiedSince = fakeIssue.LastModified 
.Subtract(TimeSpan.FromDays(1)); // <1> 
Response = Client.SendAsync(Request) .Result; 


issue = Response.Content.ReadAsAsync<IssueState>().Result; 


}); 


， 源 服务 器 上 的 资源 表示 在 最 后 一 次 由 中 间 层 








"Then a LastModified header is returned". 


f(O => 
{ 


Response. Content.Headers.LastModified.ShouldEqual(fakeIssue.LastModified) ; 
}); 


"Then a CacheControl header is returned". 
f(O => 
{ 
Response.Headers.CacheControl. Public. ShouldBeTrue(); 
Response.Headers.CacheControl.MaxAge.ShouldEqual(TimeSpan.FromMinutes(5)); 
}) 
"Then a '200 OK' status is returned". 
f(() => Response. StatusCode.ShouldEqual(HttpStatusCode.OK)); // <2> 
"Then it is returned". 
f(() => issue.ShouldNotBeNull()); // <3> 


和 前 一 个 发 送 条 件 GET 的 测试 相 比 ， 这 个 测试 做 了 一 些小 改动 。 这 个 测试 修改 了 
IfModifiedSince 标 头 的 值 ， 发 送 的 时 间 不 是 待 验证 问题 中 的 LastModified 字段 值 ， 而 是 一 
个 更 旧 的 时 间 。 在 这 种 情况 下 ，Get 方法 的 实现 会 返回 一 个 状态 码 200 0K， 以 及 资源 表示 
的 一 份 新 副本 <3>。 


8.6 ”冲突 检测 


我 们 已 经 讨论 了 如 何 使 用 条 件 GET 重新 验证 缓存 的 资源 表示 ， 现 在 要 介绍 和 条 件 GET 对 
应 的 更 新 操作 : 条件 PUT 或 条 件 PATCH。 当 同时 对 一 个 资源 进行 多 个 更 新 时 ， 我 们 可 以 使 
用 条 件 PUT/PATCH 检测 可 能 发 生 的 冲突 。 条 件 PUT/PATCH 使 用 先 写 / 先 赢 (first-write/first- 
win) 的 方法 解决 冲突 ， 也 就 是 说 ， 只 有 当 源 服务 器 上 的 资源 在 发 送 给 客户 端 后 没有 发 生 改 
变 时 ， 这 个 客户 端 才 能 对 这 个 资源 进行 更 新 操作 ， 否 则 就 会 收 到 一 个 冲突 错误 (HTTP 状 
态 码 409 Conflict), 











条 件 PUT/PATCH 也 使 用 If-None-Match 和 If-Modified-SInce 标 头 代表 资源 版 本 ， 或 者 与 待 
更 新 的 资源 表示 形成 相关 的 时 间 改 。 假 设 两 个 客户 端 (X1 和 X2) 试图 更 新 同一 个 资源 
R1， 下 面 的 步骤 详细 介绍 了 冲突 检测 对 这 一 情况 的 的 处 理 方法 。 



































(1) 客户 端 Xl 对 R1 (版 本 1) 执行 一 个 GET 操作 ， 得 到 的 HTTP 响应 包含 了 资源 表示 ， 标 
头 中 包含 资源 当前 版 本 (此 时 版 本 为 V1) 的 ETag (也 可 以 使 用 Last-modified 标 头 ) 。 
(2) 客户 端 X2 对 同一 资源 R1 (版 本 1) 执行 一 个 GET 操作 ， 得 到 的 资源 表示 与 客户 端 X1 

相同 。 

(3) 客户 端 X2 对 R1 执行 一 个 PUT/PATCH 操作 ， 更 新 资源 表示 。 这 个 请 求 包含 了 资源 表示 
的 修改 版 本 ， 以 及 带 有 当前 资源 版 本 (V1) 的 If-None-Match 标 头 。 更 新 操作 的 结果 
是 ， 服 务 器 返回 一 个 状态 码 为 OK 的 响应 ， 并 修改 了 资源 版 本 号 (V2). 

(4) 客户 端 Xl 对 R1 执行 一 个 PUT/PATCH 操作 。 这 个 请 求 消 息 也 包含 一 个 带 有 资源 版 本 V1 
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的 If-None-Match 标 头 。 服 务 器 检测 到 这 个 资源 在 以 V1 版 本 发 送 之 后 已 经 发 生 了 改变 ， 


因此 返回 一 个 状态 码 为 499 Conflict 的 响应 。 


8.7 ”实现 冲突 检测 
示例 8-8 展示 了 我 们 的 第 一 个 测试 ， 这 个 测试 将 在 无 冲突 的 情况 下 更 新 一 个 问题 





也 就 是 


题 ， 
说 ，IfModifiedsince 值 ， 和 问题 的 LastModified() 字段 中 保留 部 分 的 值 相同 。 这 些 测试 方 


法 可 在 ConflictDetection 类 中 找到 。 





Scenario: Updating an issue with no conflicts 
Given an existing issue 
When a PATCH request is made with an IfModifiedSince header 
Then a '200 OK' is returned 
Then the issue should be updated 


示例 8-8: 无 冲突 情况 下 更 新 问题 的 单元 测试 


private Uri _uriIssue1 = new Uri("http://localhost/issue/1"); 


[Scenario] 
public void UpdatingAnIssueWithNoConflict() 
{ 


var fakeIssue = FakeIssues.FirstOrDefauLt(); 


"Given an existing issue". 
f(() => 
{ 
MockIssueStore.Setup(i => i.FindAsync("1")) 
.Returns(Task.FromResult(fakeIssue) ); 
MockIssueStore.Setup(i => i.UpdateAsync('"1", It.IsAny<Object>())) 
.Returns(Task.FromResult("")); 


}); 

"When a PATCH request is made with IfModifiedSince". 
F(() => 
{ 


var issue = new Issue(); 
issue.Title = "Updated title"; 


issue.Description = "Updated description"; 
Request.Method = new HttpMethod("PATCH"); 
Request.RequestUri = _uriIssue1; 


Request.Content = new ObjectContent<Issue>(issue, 
new JsonMediaTypeFormatter()); 
Request .Headers.IfModifiedSince = fakeIssue.LastModified; // <1> 
Response = Client.SendAsync(Request) .Result; 
})3 
"Then a '200 OK' status is returned". 
f(() => Response. StatusCode.ShouldEqual(HttpStatusCode.0K)); // <2> 
"Then the issue should be updated". 
f(() => MockIssueStore.Verify(i => i.UpdateAsync("1", 
It. IsAny<JObject>()))); // <3> 





示例 8-8 展示 了 第 一 个 测试 场景 的 实现 。 在 这 个 场景 中 ，IfModifiedSince 标 头 值 设 置 为 待 更 
新 问题 的 LastModified 属性 值 <1>。 既 然 IfModifiedSince 和 LastModified 值 相 同 ， 服 务 器 应 
该 检测 不 到 冲突 ， 因 此 返回 状态 码 200 0K <2>。 最 后 ， 问 题库 中 的 问题 也 得 到 了 更 新 <3>。 









































我 们 需要 修改 IssuesController 类 中 的 Patch 方法 ， 增 加 示例 8-9 所 示 的 所 有 条 件 更 新 


逻辑 。 


示例 8-9: 支持 条 件 更 新 的 新 版 本 Patch 方法 


public async Task<HttpResponseMessage> Patch(string id, JObject issueUpdate) 


{ 
var issue = await _store.FindAsync(id); 
if (issue == null) 
return Request.CreateResponse(HttpStatusCode.NotFound) ; 


if (!Request.Headers.IfModifiedSince.HasValue) // <1> 
return Request.CreateResponse(HttpStatusCode.BadRequest, 
"Missing IfModifiedSince header"); 


if (Request.Headers.IfModifiedSince != issue.LastModified) // <2> 
return Request.CreateResponse(HttpStatusCode.Conflict); // <3> 


await _store.UpdateAsync(id, tssueUpdate) ; 
return Request.CreateResponse(HttpStatusCode.0K); 


} 








示例 8-9 展示 了 Patch 方法 中 的 新 改动 。 如 果 客 户 端 没有 发 送 IfModifiedsince trek, ALA 
我 们 认为 这 个 请 求 是 无 效 的 ， 直 接 返 回 状态 码 为 496 Bad Request 的 响应 <I>; 如 果 客 户 
端 发 送 了 IfModifiedSince 标 头 ,那么 请 求 消息 中 的 IfModifiedsicne 标 头 值 将 与 待 更 新 问题 
的 LastModified 字段 比较 <2>， 如 果 二 者 不 同 ， 代 码 将 返回 状态 码 为 499 Conflict 的 响应 



































<3>。 如 果 以 上 情况 皆 不 是 ， 那 么 代码 最 后 将 更 新 问题 ， 返 回 状态 码 为 200 OK 的 响应 。 








示例 8-10 中 展示 了 下 一 个 测试 ， 测 试 检测 到 冲突 的 场景 


Scenario: Updating an issue with conflicts 
Given an existing issue 
When a PATCH request is made with an IfModifiedSince header 
Then a '409 CONFLICT’ is returned 
Then the issue is not updated 


示例 8-10: 有 冲突 情况 下 更 新 问题 的 单元 测试 
[Scenario] 
public void UpdatingAnIssueWithConflicts() 
{ 


var fakeIssue = FakeIssues.FirstOrDefault(); 


"Given an existing issue". 


f(O => 
{ 


MockIssueStore.Setup(i => i.FindAsync("1")) 
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.Returns(Task.FromResuLt(fakeIssue) ); 


]); 

"When a PATCH request is made with IfModifiedSince". 
F(() => 
{ 


var issue = new Issue(); 
issue.Title = "Updated title"; 


issue.Description = "Updated description"; 
Request.Method = new HttpMethod('"PATCH"); 
Request.RequestUri = _uriIssue1; 


Request.Content = new ObjectContent<Issue>(issue, 
new JsonMediaTypeFormatter()); 
Request.Headers.IfModifiedSince = fakeIssue.LastModified.AddDays(1); // <1> 
Response = Client.SendAsync(Request) .Result; 
H; 
"Then a '409 CONFLICT' status is returned". 
f(() => Response.StatusCode 
.ShouldEqual(HttpStatusCode.Conflict)); // <2> 
"Then the issue should be not updated". 
f(() => MockIssueStore.Verify(i => 
i.UpdateAsync("1", It.IsAny<JObject>()), Times.Never())); // <3> 
} 


示例 8-10 中 的 代码 ， 测 试 了 检测 到 冲突 的 场景 。 我 们 将 IfModifiedsince 标 头 的 值 设 置 为 
待 更 新 问题 的 LastModified 属性 值 加 一 天 <1>。 由 于 IfModifiedSince Fil LastModified 值 不 
同 ， 测 试 预期 服务 器 返回 一 个 状态 码 为 499 Conflict 的 响应 <2>。 最 后 ， 测 试 还 验证 了 问 
题库 中 的 问题 并 没有 得 到 更 新 <3>。 


8.8 变更 审计 


我 们 的 Web API 要 支持 的 另 一 个 功能 是 ， 识 别 创建 新 问题 或 者 更 新 已 有 问题 的 用 户 或 客 
户 端 ， 这 意味 着 API 实现 要 使 用 预先 定义 的 认证 方案 ， 基 于 应 用 程序 键 、 用 户 名 / 密码 、 
HMAC (Hash-based Message Authentication Code， 基 于 散 列 的 消息 认证 码 ) 或 安全 令 牌 
(如 OAuth)， 对 客户 端 进 行 认证 。 

















使 用 应 用 程序 键 可 能 是 最 简单 的 实现 方法 。 每 个 客户 端 应 用 程序 都 由 一 个 简单 固定 的 应 用 
程序 键 进行 标识 。 这 种 认证 机 制 可 能 比较 弱 ， 但 是 我 们 的 服务 提供 的 并 非 敏 感 数据 ， 任 何 
有 应 用 程序 键 的 人 都 可 以 使 用 这 些 数 据 。 公 共 服 务 ， 如 谷歌 地 图 或 公共 图 片 搜索 (例如 
Instagram 中 的 搜索 ) ， 大 多 使 用 应 用 程序 键 认 证 方案 。 使 用 应 用 程序 键 的 唯一 目的 ， 是 识 
别 客户 端 ， 以 便 对 其 应 用 不 同 的 服务 水 平 协议 (service-level agreement), ， 例 如 API 配额 或 
可 用 性 。 得 到 了 客户 端的 应 用 程序 键 ， 任 何人 都 可 以 对 其 进行 模拟 。 












































HMAC 与 应 用 程序 键 认证 的 机 制 相似 ， 但 是 使 用 基于 密 钥 的 加 密 算法 ， 以 避免 应 用 程序 
键 认证 方案 中 的 模拟 问题 。 与 基本 认证 不 同 的 是 ， 密 钥 或 密码 不 会 在 每 个 消息 中 以 明文 
BGK, HMAC 或 散 列 是 基于 密 钥 ， 使 用 HTTP 请 求 消息 的 部 分 内 容 生 成 的 ， 并 包含 在 认 
证 标 头 中 。 服 务 器 可 以 通过 认证 标 头 中 附带 的 HMAC， 验 证 客户 端的 身份 。 这 种 认证 模 
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式 特别 适合 云 计算 。 在 云 计 算 环境 中 ， 服 务 提供 方 ， 如 AWS (Amazon Web Services) 或 
Windows Azure， 使 用 一 个 键 值 来 识别 用 户 ， 以 提供 正确 的 服务 和 私有 数据 。 不 管用 户 使 
用 什么 客户 端 应 用 程序 来 使 用 服务 和 数据 ， 这 个 键 值 的 主要 目的 是 识别 用 户 的 身份 。 虽 然 
存在 好 儿 种 HMAC 认证 的 实现 ， 我 们 在 这 里 将 只 介绍 一 个 对 HMAC 认证 进行 标准 化 的 新 
兴 规 范 Hawk。 











最 后 一 种 认证 方案 基于 安全 令 牌 ， 可 能 是 最 为 复杂 的 一 种 方案 。OAuth 就 是 这 种 方案 的 一 
种 ， 设 计 用 于 在 Web 2.0 中 进行 授权 认证 。 拥 有 数据 的 服务 可 以 使 用 OAuth 与 其 他 服务 或 
应 用 程序 共享 数据 ， 而 不 会 泄露 数据 所 有 者 的 身份 。 


第 15 章 将 详细 讨论 以 上 提 到 的 这 些 认证 方案 。 在 本 章 中 ， 我 们 将 使 用 Hawk， 在 设置 问题 
的 审计 信息 前 ， 对 客户 端 应 用 程序 进行 认证 。 


8.9 使 用 Hawk 认 证 实现 变更 审计 


我 们 的 第 一 个 测试 将 创建 一 个 新 问题 ， 这 个 问题 带 有 关于 创建 者 的 审计 信息 。 因 此 ， 这 个 
测试 也 将 实现 使 用 Hawk， 对 客户 端 进行 HMAC 认证 。 这 些 测试 的 代码 位 于 CodeAuditing 
类 中 。 


























Scenario: Creating a new issue 
Given a new issue 
When a POST request is made with an Authorization header containing the user 
identifier 
Then a '201 Created' status is returned 
Then the issue should be added with auditing information 
Then the response location header will be set to the resource location 


为 了 在 实现 中 增加 Hawk 认证 ， 我 们 要 使 用 GitHub (https://github.com/pcibraro/hawknet ) 
上 一 个 现成 的 开源 实现 HawkNet。HawkNet 支持 与 多 个 Web API 框架 的 集成 ， 其 中 就 包 
括 ASP.NET Web API, HawkNet 通过 HTTP 消息 处 理 程序 ， 实 现 了 与 ASP.NET WEb API 
的 集成 (参见 示例 8-11)。 客 户 端 使 用 一 个 处 理 程序 ， 在 每 个 发 出 的 调用 中 自动 加 入 Hawk 
认证 标 头 ， 服 务 器 端 使 用 另 一 个 处 理 程 序 ， 验 证 标 头 ， 对 客户 端 进行 认证 。 
































示例 8-11: 在 HttpCLient 实例 中 注入 HawkClientMessageHandler 


Credentials = new HawkCredential 


{ 
Id = "TestClient", 
Algorithm = "hmacsha256", 
Key = "werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn", 
User = "test" 
}; // <1> 


var server = new HttpServer(GetConfiguration()); 
Client = new HttpClient(new HawkClientMessageHandler(server, Credentials)); // <2> 





示例 8-11 展示 了 如 何在 测试 使 用 的 HttpClient 实例 中 注入 HawkClientMessageHandler , 
HawkNet 使 用 HawkCredential 类 进行 各 种 配置 ， 设 定 如 何 生 成 Hawk 标 头 。 我 们 的 测试 
配置 这 个 HawkCredential 类 使 用 SHA-256 算法 生成 HMAC， 还 配置 了 密 钥 、 应 用 程序 id 
(TestCLient)， 以 及 与 这 个 密 钥 关联 的 用 户 (test) <1>, HawkCredential 类 进行 实例 化 和 
配置 之 后 ， 就 传递 给 注入 HttpCLient 实例 的 HawkClientMessageHandler <2>。 


除 此 之 外 ， 服 务 器 也 需要 配置 对 应 的 消息 处 理 程序 ， 用 于 验证 标 头 和 认证 客户 端 。 
HawkNet 为 此 提供 一 个 HawkMessageHandler 类 ， 这 个 类 可 以 作为 路 由 配置 的 一 部 分 注入 ， 
或 者 作为 全 局 处 理 程序 注入 (参见 示例 8-12)。 








示例 8-12: 在 路 由 配置 中 注入 HawkMessageHandler 


Credentials = new HawkCredential 


{ 
Id = "TestClient", 
Algorithm = "hmacsha256", 
Key = "werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn", 
User = "test" 
J}; 


var config = new HttpConfiguration(); 


var serverHandler = new HawkMessageHandler (new HttpControllerDispatcher(config), 
(id) => Credentials); 


config.Routes .MapHttpRoute("DefaultApi", "{controller}/{id}", new { id = 
RouteParameter.Optional }, null, serverHandler); 








一 旦 发 送 和 认证 Hawk 标 头 的 处 理 程序 就 位 ， 我 们 就 可 以 开始 编写 测试 ， 测 试 创建 问题 的 
第 一 个 场景 了 。 示 例 8-13 展示 了 这 个 测试 的 最 终 实现 。 








示例 8-13: 创建 一 个 新 问题 的 实现 
[Scenario] 
public void CreatingANewIssue() 


{ 


Issue issue = null; 


"Given a new issue". 
f(() => 
{ 


issue = new Issue 


{ 


Description = "A new issue", 
Title = "A new issue" 


Js 
var newIssue = new Issue { Id = "1" }; 


MockIssueStore 
.Setup(i => i.CreateAsync(issue, "test")) 





.Returns(Task.FromResult(newIssue) ) ; 
]); 
"When a POST request is made with an Authorization header containing the user 
identifier". 
f(O => 
{ 
Request.Method = HttpMethod.Post; 
Request.RequestUri = _issues; 
Request.Content = new ObjectContent<Issue>(issue, 
new JsonMediaTypeFormatter()); 
Response = Client.SendAsync(Request) .Result; 
}); 
"Then a '201 Created' status is returned". 
f(() => Response. StatusCode. ShouldEqual(HttpStatusCode.Created)); 
"Then the issue should be added with auditing information". 
f(() => MockIssueStore.Verify(i => i.CreateAsync(issue, "test"))); // <1> 
"Then the response location header will be set to the resource location". 
f(() => Response.Headers.Location.AbsoluteUri.ShouldEqual 
("http://localhost/issue/1")); 
} 


这 个 测试 主要 验证 的 是 ， 创 建 的 新 问题 在 问题 库 中 存储 正确 ， 并 包含 了 认证 用 户 信 息 
test<1>。 我 们 修改 了 IIssueStore 接口 的 CreateAsync 方法 ， 增 加 了 一 个 参数 ， 代 表 创 建 
问题 的 用 户 。IssueController 类 的 Post 方法 负责 从 认证 用 户 得 到 这 个 参数 值 ， 并 传递 给 
CreateAsync (参见 示例 8-14). 


示例 8-14: 更 新 版 本 的 Post 方法 
[Authorize] 
public async Task<HttpResponseMessage> Post(Issue issue) 


{ 
var newIssue = await _store.CreateAsync(issue, User.Identity.Name); // <1> 
var response = Request.CreateResponse(HttpStatusCode. Created) ; 
response.Headers.Location = _LinkFactory.Self(newIssue.Id).Href; 
return response; 


} 


认证 用 户 可 以 通过 User.Identity 属性 得 到 。HawkMessageHanlder 在 验证 了 收 到 的 
Authorization 标 头 后 ， 设 置 User.Identity 属性 的 值 。 这 个 用 户 和 接收 到 的 问题 一 起 作为 
参数 传递 给 CreateAsync 方法 <1>。 此 外 ，Post 方法 受到 Authorize 属性 修饰 ， 以 拒绝 任 
何 匿名 的 调用 。 














Scenario: Updating an issue 
Given an existing issue 
When a PATCH request is made with an Authorization header containing the 
user identifier 
Then a '200 OK' is returned 
Then the issue should be updated with auditing information 


验证 这 个 场景 的 测试 实现 ， 也 需要 检查 IIssuestore 中 的 问题 修改 是 否 正确 ， 以 及 是 否 带 
有 认证 用 户 信息 (参见 示例 8-15)。 





示例 8-15: 更 新 问题 的 测试 实现 
[Scenario] 
public void UpdatingAnIssue() 
{ 


var fakeIssue = FakeIssues.FirstOrDefauLt(); 


"Given an existing issue". 
F(() => 
{ 
MockIssueStore 
.Setup(i => i.FindAsync("1")) 
.Returns(Task.FromResult(fakeIssue) ); 
MockIssueStore 
.Setup(i => i.UpdateAsync("1", It.IsAny<Object>(), It.IsAny<string>())) 
.Returns(Task.FromResult("")); 
})3 
"When a PATCH request is made with an Authorization header containing the user 
identifier". 
F(() => 
{ 
var issue = new Issue(); 
issue.Title = "Updated title"; 
issue.Description = "Updated description"; 
Request.Method = new HttpMethod("PATCH"); 
Request.Headers.IfModifiedSince = fakeIssue.LastModified; 
Request.RequestUri = _uriIssue1; 
Request.Content = new ObjectContent<Issue>(issue, new JsonMediaTypeFormatter()); 
Response = Client.SendAsync(Request) .Result; 
})3 
"Then a '200 OK' status is returned". 
f(() => Response. StatusCode. ShouldEqual(HttpStatusCode.OK)); 
"Then the issue should be updated with auditing information". 
f(() => MockIssueStore.Verify(i => i.UpdateAsync("1", It.IsAny<JObject>(), 
"test"))); // <1> 
} 


IIssueStore 接口 的 UpdateAsync 方法 也 改 为 多 使 用 一 个 参数 ， 代 表 更 新 问题 的 用 户 <1>。 


示例 8-16 展示 了 Patch 方法 的 修改 版 本 ， 方 法 中 对 IIssueStore 的 UpdateAsync 调用 进行 
了 修改 ， 传 和 人 认证 用 户 参数 。 


示例 8-16: 更 新 版 本 的 Patch 方法 
[Authorize] 
public async Task<HttpResponseMessage> Patch(string id, JObject issueUpdate) 
{ 
var issue = await _store.FindAsync(id); 
if (issue == null) 
return Request.CreateResponse(HttpStatusCode.NotFound) ; 


if (!Request.Headers.IfModifiedSince.HasVaLue) 
return Request.CreateResponse(HttpStatusCode.BadRequest, 
"Missing IfModifiedSince header"); 





if (Request.Headers.IfModifiedSince != issue.LastModified) 
return Request.CreateResponse(HttpStatusCode.Conflict); 


await _store.UpdateAsync(id, issueUpdate, User.Identity.Name); // <1> 
return Request.CreateResponse(HttpStatusCode.OK) ; 


} 


8.10 ”跟踪 





在 一 个 不 具备 集成 开发 环境 或 者 代码 调试 工具 不 可 用 的 环境 里 ， 或 者 在 开发 早期 API 性 能 


还 不 稳定 ， 有 一 些 随机 的 难以 确定 的 问题 发 生 时 ， 要 解决 问题 或 者 调试 Web API， 跟 踪 是 
一 项 不 可 替代 的 功能 。ASP.NET Web API 自 带 一 个 跟踪 架构 ， 可 以 用 于 跟踪 框架 自身 的 任 
何 行为 ， 或 者 Web API 实现 中 的 任何 定制 代码 。 


ASP.NET Web API 


跟踪 架构 的 核心 组 件 或 服务 是 System.Web. Http. Tracing. ITraceWriter 


接口 ， 这 个 接口 只 包含 一 个 方法 Trace， 用 于 生成 一 个 新 的 跟踪 条 目 。 


示例 8-17: ITraceWriter 接口 定义 


public interface ITraceWriter 


{ 


void Trace(HttpRequestMessage request, string category, TraceLevel level, 
Action<TraceRecord> traceAction); 


} 


Trace 方法 使 用 如 下 参数 。 


e request 


与 跟踪 相关 的 请 求 消息 。 


e category 


与 跟踪 条 目 相 关 的 类 别 ， 便 于 组 织 或 过 滤 跟 踪 条 目 。 


e level 


AHRR, PTD Picture H o 


e traceAction 


对 生成 跟踪 条 目的 方法 的 委托 。 


虽然 这 个 跟踪 架构 没有 绑 定 到 NET 中 的 任何 日 志 框 架 


Library Logging 











如 Log4Net、NLog 或 Enterprise 
但 是 这 个 架构 提供 了 一 个 默认 的 日 志 实 现 ， 称 为 System.web.Http. 














Tracing.SystemDiagnosticsTraceWritter, {EJH System.Diagnostics.Trace.TraceSource, 


要 使 用 其 他 的 日 志 


示例 8-18 展示 了 如 


EX, REAME ITraceWritter 服务 接口 的 实现 。 





可 在 Web API 配置 对 象 中 注入 一 个 定制 实现 。 





示例 8-18: ITraceWritter 配置 


HttpConfiguration config = new HttpConfiguration(); config.Services. 
Replace(typeof(ITraceWriter), new SystemDiagnosticsTraceWriter()); 


8.11 实现 跟踪 


我 们 有 一 个 场景 ,测试 IssueController 类 中 所 有 方法 的 大 致 跟踪 。 测 试 代码 位 于 Tracing 
类 中 。 


Scenario: Creating, Updating, Deleting, or Retrieving an issue 
Given an existing or new issue 
When a request is made 
When the diagnostics tracing is enabled 
Then the diagnostics tracing information is generated 


在 对 这 个 场景 编写 测试 前 ， 我 们 要 做 的 第 一 件 事 情 是 配置 ITTracewriter 的 一 个 实例 ， 用 于 
检验 跟踪 功能 是 否 真 的 起 作用 。 详 见 示 例 8-19。 





示例 8-19: 测试 的 ITracewriter 配置 
public abstract class IssuesFeature 


{ 


public Mock<ITraceWriter> MockTracer; 


public IssuesFeature() 
{ 
} 


private HttpConfiguration GetConfiguration() 


{ 


var config = new HttpConfiguration(); 
MockTracer = new Mock<ITraceWriter>(MockBehavior .Loose); 
config.Services.Replace(typeof(ITraceWriter), MockTracer.Object); // <1> 


return config; 


} 
} 


示例 8-19 展示 了 如 何在 Web API 使 用 的 HttpConfiguration 实例 中 ， 注 入 一 个 模拟 实例 
<1>。 我 们 的 测试 将 使 用 这 个 模拟 实例 (参见 示例 8-20) ， 验 证 控制 器 方法 对 Trace 方法 的 
调用 。 


示例 8-20: 跟踪 测试 实现 
public class Tracing : IssuesFeature 


{ 


private Uri _uriIssue1 = new Uri("http://localhost/issue/1"); 





[Scenario] 
public void RetrievingAnIssue() 
{ 
IssueState issue = null; 
var fakeIssue = FakeIssues.FirstOrDefauLt(); 


"Given an existing or new issue". 
f(() => 
{ 
MockIssueStore 
.Setup(i => i.FindAsync("1")) 
.Returns(Task.FromResuLt(fakeIssue))); 
} 
"When a request is made". 


f(() => 
{ 
Request.RequestUri = _urilIssue1; 
Response = Client 
. SendAsync(Request) 
.Result; 


issue = Response.Content 
.ReadAsAsync<IssueState>() 


.Result; 
}); 
"When the diagnostics tracing is enabled". 
F(() => 
{ 


Configuration. Services 
.GetService(typeof(ITraceWriter)).ShouldNotBeNull(); // <1> 


IDE 

"Then the diagnostics tracing information is generated". 
f(() => 
{ 


MockTracer .Verify(m => m.Trace(It.IsAny<HttpRequestMessage>(), // <2> 
typeof (IssueController).FullName, 
TraceLevel.Debug, 
It. IsAny<Action<TraceRecord>>())); 
p; 
} 
} 


示例 8-20 中 的 测试 代码 验证 了 当前 HttpConfiguration 实例 中 配置 了 ITracewriter 服务 ， 
并 检验 IssueController 类 (参见 示例 8-21) ， 向 配置 的 模拟 实例 发 送 了 跟踪 消息 。 


示例 8-21: IssueController 中 的 跟踪 语句 
public async Task<HttpResponseMessage> Get(string id) 


{ 


var tracer = this.Configuration.Services.GetTraceWriter(); // <1> 


var result = await _store.FindAsync(id); 
if (result == null) 





tracer.Trace(Request, 
TraceCategory, TraceLevel.Debug, 
"Issue with id {0} not found", id); // <2> 


return Request.CreateResponse(HttpStatusCode.NotFound) ; 





HttpConfiguration 类 提供 了 一 个 扩展 方法 或 捷径 ， 可 以 获得 配置 的 ITraceWriter 实例 ， 医 
此 可 以 在 实现 中 由 定制 代码 使 用 。 示 例 8-21 展示 了 如 何 修改 IssueController 类 ， 以 获得 
ITraceWriter 的 引用 <1>， 然 后 用 来 在 返回 响应 之 前 输出 跟踪 信息 ， 说 明 问 题 未 找到 <2>。 

















8.12 ”小结 


本 章 介 绍 了 对 现 有 Web API 进行 改进 的 几 个 重要 方面 ， 如 缓存 、 冲 突 管理 、 审 计 和 跟踪 。 
虽然 有 些 功能 在 某 些 情况 下 并 不 适用 ， 但 是 了 解 了 这 些 功 能 带 来 的 好 处 ， 你 就 可 以 正确 使 
用 它们 。 
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一 个 巴掌 拍 不 响 。 


我 们 已 经 说 过 ， 贯 穿 这 本 书 的 目标 是 构建 一 个 可 演化 的 系统 。 到 目前 为 止 ， 我 们 的 大 部 分 
精力 都 放 在 构建 API 上 ， 关 注 如 何 使 客户 端 能 够 保持 松 看 合 ， 以 实现 可 演化 系统 的 目标 。 
遗憾 的 是 ， 服 务 器 API 只 能 为 松 契 合 提供 条 件 ， 并 不 能 防止 紧 克 合 的 发 生 。 不 管 我 们 如 何 
使 用 超 媒 体 、 标 准 媒体 类 型 和 自 描述 性 消息 ， 都 不 能 阻止 客户 端 使 用 硬 编码 的 URI， 也 不 
能 保证 客户 端 不 假定 自己 了 解 响应 消息 的 内 容 类 型 和 语义 。 


公布 一 个 Web API, 一 定 程度 上 是 为 了 给 API 使 用 者 提供 指导 意见 ， 说 明 如 何 使 用 服务 能 
够 更 好 地 利用 Web 架构 的 功能 。 我 们 需要 告诉 客户 端的 开发 者 ， 如 何 使 用 API， 避 免 使 用 
那些 可 能 发 生变 化 的 依赖 物 。 





为 客户 端 开发 者 提供 指导 ， 我 们 可 以 编写 文档 ， 但 是 文档 通常 只 能 解决 部 分 问题 。API 提 
供 者 希望 API 使 用 者 的 体验 尽 可 能 地 愉快 ， 因 此 经 常会 提供 客户 端 程序 库 ， 企 图 使 客户 端 
开发 者 能 够 很 快 开始 工作 。 可 悲 的 是 ， 人 们 常常 认为 ， 如 果 不 能 在 五 分 钟 内 学 会 使 用 一 个 
软件 程序 库 ， 那 么 这 个 程序 库 肯 定 写 得 不 好 。 可 惜 ， 这 种 对 易 用 性 的 优选 法 没有 认识 到 简 
单 和 容易 之 间 的 细微 差别 (http://www.infoq.com/presentations/Simple-Made-Easy ) 。 


























在 努力 提高 API 易 用 性 的 过 程 中 ，API 提供 者 经 常会 创建 一 些 客户 端 程序 库 ， 对 基于 
HTTP 的 API 进行 封装 ， 从 而 失去 了 Web 架构 的 许多 优点 ， 最 后 导致 客户 端 应 用 程序 与 客 
户 端 程序 库 紧 密 耦 合 ， 而 客户 端 程序 库 又 与 服务 器 API 紧密 耦合 。 在 本 章 中 ， 我 们 将 更 详 
细 地 讨论 这 种 客户 端 程序 库 的 负面 影响 ， 然 后 介绍 一 种 替代 方法 ， 既 和 封装 API 一 样 易于 
使 用 ， 又 不 会 导致 同样 的 问题 。 接 着 ， 我 们 将 讨论 构建 客户 端 逻 辑 和 管理 客户 端 状态 的 技 
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术 ， 使 客户 端 能 够 灵活 适应 变化 。 


2 LL 
91 客户 端 程序 库 
使 用 客户 端 程序 库 ， 目 的 是 提高 抽象 度 ， 使 客户 端 应 用 程序 可 以 编写 与 应 用 程序 域 相关 的 
代码 。 通 过 重用 标准 代码 ， 创 建 HTTP 请 求 和 解析 响应 ， 开 发 者 可 以 将 精力 集中 在 功能 实 
现 上 。 

















9.1.1 封装 库 
API 封装 库 的 例子 比比 皆 是 。 如 果 你 搜索 Programmable Web (http://www.programma 
bleweb.com/) 这 样 的 网 站 ， 会 得 到 很 多 的 结果 ， 指 向 的 网 站 都 提供 几 十 种 不 同 编程 语言 的 
客户 端 程序 库 。 有 的 时 候 ， 这 些 客户 端 程序 库 来 自 API 提供 者 ， 但 是 在 如 今 ， 很 多 的 程序 
库 是 社区 参与 者 提供 的 。API 提供 者 发 现 ， 维 护 所 有 这 些 不 同 版 本 的 程序 库 ， 需 要 的 工作 
EKK. 


无 论 一 个 客户 端 APT 封装 程序 的 具体 提供 者 是 谁 ， 代 码 通 常 是 这 样 的 : 























var api = new IssueTrackingApi(apiToken) ; 

var issue = api.GetIssue(issueld); 

issue.Description = "Here is a description for my issue"; 
issue. Save(); 


这 段 代 码 有 一 个 最 基本 的 问题 : 客户 端 开 发 者 不 再 了 解 ， 这 四 行 代 码 中 的 哪 一 行 会 发 出 网 
络 请 求 ， 哪 一 行 不 发 出 请 求 。 把 发 出 网 络 请 求 的 标准 代码 抽象 出 去 ， 这 种 做 法 并 没有 问 
题 ， 但 是 如 果 完 全 把 这 些 高 延迟 交互 发 生 的 位 置 隐藏 起 来 ， 客 户 端 应 用 程序 的 开发 者 就 很 
难 写 出 网 络 效率 高 的 应 用 程序 。 








1. 可 靠 性 

开发 基于 网 络 的 应 用 程序 ， 面 对 的 挑战 之 一 是 网 络 不 可 靠 ， 在 无 线 网 络 和 蜂窝 移动 通信 环 
境 中 这 个 问题 尤为 严重 。 作 为 一 个 应 用 程序 协议 ，HTTP 具有 一 些 功能 ， 可 以 使 应 用 程序 
容忍 这 样 不 可 靠 的 传输 介质 。 调 用 如 GetIssue 或 Save 这 样 的 方法 ， 可 能 得 到 的 结果 有 两 
种 : 一 种 是 成 功 以 及 预期 的 返回 类 型 ， 另 一 种 是 异常 。HTTP 将 请 求 区 分 为 安全 和 不 安全 
的 ， 稚 等 和 非 窜 等 的 。 根 据 这 些 分 类 ， 客 户 端 应 用 程序 可 以 解释 标准 的 状态 码 ， 决 定 在 失 
败 时 采取 何 种 补救 措施 。 在 面向 对 象 和 过 程 化 的 编程 中 ， 并 没有 这 样 的 约定 。 我 可 以 猜测 
GetIssue 是 安全 的 ，Save 是 不 安全 而 且 (在 这 个 代码 示例 中 ) SY. (AE, PAGER 
是 根据 方法 名 ， 猜 想 其 底层 的 客户 端 行为 ， 而 做 出 了 这 样 的 推断 。 将 HTTP 请 求 隐藏 在 过 
程 调用 之 后 ， 就 隐藏 了 HTTP 的 可 靠 性 功能 ， 人 迫使 客户 端 开发 者 重新 创建 自己 的 约定 和 标 
准 ， 重 新 获得 这 种 可 靠 性 。 















































客户 端 程序 库 可 以 使 用 某 些 可 靠 性 机 制 ， 如 重 试 ， 一 些 设计 比较 好 的 程序 库 可 能 会 采取 这 
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种 做 法 。 但 是 ， 编 写 程序 库 的 开发 人 员 并 不 知道 客户 端 应 用 程序 的 可 靠 性 需求 。 同 一 种 矫 
正 行为 ， 对 一 个 客户 端 应 用 可 能 是 有 益 的 ， 而 对 男 一 个 应 用 并 不 适用 。 在 夜间 抓 取 数据 源 
的 批 处 理 程 序 可 能 很 乐于 将 一 个 请 求 重 试 两 三 次 ， 每 个 请 求 间 隔 等 待 几 分 钟 ， 但 如 果 等 待 
响应 的 是 人 类 ， 伙 怕 就 不 会 这 么 耐心 等 待 响应 结果 了 。 




















HTTP 请 求 的 结果 并 不 仅仅 会 影响 处 理 服务 临时 中 断 的 方式 。 请 求 结果 可 能 有 : 请 求 的 资 
源 不 存在 (410 Gone)、 资 源 已 移 走 (303 See other)、 禁 止 访问 (403 Forbidden) 或 者 需 
要 等 待 资源 创建 (202)。 响 应 的 内 容 类 型 (Content-Type) 也 可 能 和 上 次 请 求 时 不 同 。 所 
有 这 些 都 不 是 执行 请 求 的 失败 结果 。 对 于 一 个 预期 会 随 着 时 间 演 化 的 系统 ， 这 些 都 是 在 对 
其 请 求 信 息 时 得 到 的 有 效 响应 。 如 果 我 们 要 构建 一 个 能 够 多 年 使 用 的 可 靠 客户 端 ， 就 需要 
处 理 所 有 这 些 情况 。 
































我 经 常 看 到 ，API 文档 对 一 个 特定 API 资源 可 能 返回 的 状态 码 进行 描述 。 不 幸 的 是 ，API 
返回 的 状态 码 是 不 受 约束 的 。 在 每 个 HTTP 请 求 的 处 理 中 ， 都 有 许多 中 间 层 的 参与 : 客户 
端 连接 程序 、 代 理 、 缓 在、 负载 均衡 、 反 向 代理 和 应 用 程序 中 间 件 ， 诸 如 此 类 。 任 何 中 间 
层 都 可 能 中 断 一 个 请 求 ， 返 回 另 外 一 些 状态 码 。 客 户 端 需要 能 够 处 理 对 所 有 资源 的 所 有 响 
应 码 。 在 构建 客户 端 时 ， 如 果 假 定 一 个 资源 从 来 不 会 返回 状态 码 393， 那 么 这 种 做 法 和 硬 
编码 URI 一 样 ， 都 引入 了 隐藏 的 耦合 。 


2. 响应 类 型 

像 GetIssue 这 样 的 方法 ， 假 定 返回 的 响应 可 以 转换 为 一 个 Issue 对 象 。 通 过 在 客户 端 程序 
库 中 加 入 一 些 基本 的 内 容 协 商 代 码 ， 你 可 以 实现 一 定 的 灵活 性 ， 以 处 理 JSON 最 终 由 其 他 
一 些 传输 格式 替代 (正如 XML 如 今 已 经 不 再 流行 ) 的 情况 。 但 是 ， 有 些 可 以 利用 HTTP 
实现 的 功能 ， 在 这 种 方法 严格 受 限 的 合约 中 是 无 法 实现 的 。 请 看 下 面 的 请 求 : 






























































GET /IssueSearch?priority=high&AssignedTo=Dave 


在 过 程 化 的 封装 程序 库 中 ， 对 应 的 方法 签名 会 是 这 样 的 : 





public List<Issue> SearchIssues(int priority, string assignedTo); 


返回 资源 的 媒体 类 型 可 能 是 CoLLection+Json， 这 种 格式 非常 适合 用 于 返回 列表 。 但 是 ， 如 
PARA a BERTIE EVE AR EA RA YE? 服务 器 可 能 会 决定 不 返回 只 有 一 个 Issue 
的 Collection+Json 列表 ， 而 是 返回 一 个 Issue 完整 的 application/Issuet+Json 表示 。 过 程 
化 的 程序 库 无 法 支持 这 种 灵活 性 ， 除 非 是 使 用 object 类 型 的 返回 值 ， 而 这 又 不 符合 强 类 型 
封闭 程序 库 的 目标 。API 开发 者 可 能 出 于 各 种 原因 ， 不 希望 在 响应 中 引入 这 种 变动 ， 但 是 
在 某 些 情况 下 这 种 功能 是 极 有 价值 的 。 例 如 : 带 有 一 列 条 目 和 相关 支出 凭据 的 开支 报告 。 
这 些 凭据 可 能 是 PDF 文件 、TIFF 文件 、 位 图 、HTML 页 面 或 电子 邮件 。 你 不 可 能 在 一 个 
方法 签名 中 支持 所 有 这 些 资 源 的 强 类 型 表示 。 
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3. 生存 期 

在 之 前 的 客户 端 代码 片段 中 ， 我 们 初始 化 了 一 个 Issue 对 象 。 这 个 对 象 的 状态 来 自 服 务 器 
返回 的 资源 表示 。 服 务 器 返回 的 资源 表示 很 可 能 带 有 一 个 缓存 控制 标 头 。 如 果 缓 存 控制 标 
头 如 下 段 所 示 ， 那 么 服务 器 声明 了 数据 在 随后 的 60 秒 内 是 有 效 的 : 








Cache-Control: private;max-age=60 





如 果 存 在 适当 的 缓存 支持 ， 那 么 在 随后 60 秒 内 ， 对 这 个 Issue 的 任何 获取 操作 都 会 不 会 产 
生 真 正 的 网 络 往返 通信 ， 而 是 从 缓存 返回 资源 表示 。60 秒 之 后 ， 对 这 个 Issue 的 任何 获取 
操作 都 将 产生 一 个 网 络 请 求 ， 得 到 最 新 的 信息 。 如 果 把 资源 表示 数据 复制 到 一 个 本 地 对 象 
中 ， 忽 略 返回 的 表示 ， 就 把 这 个 数据 的 生存 期 与 对 象 的 生存 期 绑 定 在 了 一 起 ，60 秒 的 max- 
age 信息 失效 。 不 管 信 息 如 何 陈 旧 ， 资 源 表示 数据 会 一 直 得 到 保存 和 重用 ， 直 到 这 个 对 象 
销毁 ， 新 的 对 象 生 成 。 在 处 理 并 发 问题 时 ， 由 服务 器 控制 数据 的 生存 期 是 很 重要 的 。 服 务 
器 是 数据 的 所 有 者 ， 对 数据 的 易 变性 有 最 准确 的 理解 。 如 果 依 赖 客户 端 制定 缓存 规则 ， 客 
户 端 就 需要 对 服务 器 上 的 数据 有 比 通常 所 需 更 多 的 了 解 。 


如 果 客 户 端 程序 库 建 立 对 象 关系 ， 那 么 包含 陈旧 数据 的 对 象 实例 会 带 来 更 严重 的 问题 。 在 
封装 API 中， 你 经 常 看 到 用 一 个 对 象 获取 资源 表示 ， 以 填充 相关 的 其 他 对 象 ， 常 见 做 法 是 
使 用 基于 属性 的 延迟 加 载 : 
































var issue = api.GetIssue(issueld); 
var reportedByuser = issue.ReportedBy; 





在 获取 数据 库 信息 的 ORM (ObjectrRelated Mapping， 对 象 关 系 映射 ) 程序 库 中 ， 这 种 加 
载 属性 的 方法 极为 常见 。 但 是 ， 在 API 封装 库 中 这 样 做 ,会 将 User 对 象 的 生存 期 与 Issue 
对 象 的 生存 期 绑 定 。 也 就 是 说 ， 你 不 仅 忽 略 了 HTTP 的 缓存 生存 期 信息 ， 还 在 数据 表示 之 
间 创 建 了 生存 期 依赖 ， 其 结果 与 我 们 希望 的 正好 相反 。 一 个 问题 资源 很 可 能 比 用 户 资 源 修 
改 更 为 频繁 ， 用 户 资源 可 能 由 多 个 问题 资源 重用 。 可 是 ， 我 们 的 对 象 关 系 把 User 的 生存 期 
和 Issue 的 生存 期 绑 定 ， 这 不 是 最 优 的 方式 。 为 了 解决 这 个 问题 ，ORM 库 经 常会 创建 新 的 
生存 期 范围 ， 称 为 会 话 (session) 或 工作 单元 (unit of work) ， 由 这 些 容器 来 管理 对 象 生存 
期 。 这 种 解决 方法 给 客户 端 增加 了 不 必要 的 复杂 度 。 我 们 原本 可 以 利用 HTTP 协议 ， 使 用 
服务 器 提供 的 缓存 信息 来 避免 这 些 问题 ， 为 此 我 们 不 能 再 将 HITP 隐藏 在 封装 程序 后 面 。 


4. 每 个 人 都 有 自己 的 风格 

客户 端 封装 程序 库 的 另 一 个 问题 是 ， 这 些 库 各 自 维护 自身 的 协议 状态 ， 使 API 的 使 用 更 加 
混乱 。 通 过 与 客户 端 程序 库 的 一 系列 交互 ， 未 来 交互 基于 存储 的 状态 进行 修改 。 这 些 存储 
的 状态 可 能 是 认证 信息 ， 或 者 其 他 修改 请 求 的 偏好 设置 。 不 同 的 API 各 自 实现 自己 的 客户 
端 程序 库 ， 创 建 自己 的 交互 模型 ， 增 加 了 开发 者 的 学 习 曲 线 。 当 客户 端 程序 库 必须 使 用 多 
个 API 才能 完成 工作 时 ， 这 种 风格 差异 更 加 令 人 烦恼 。 访 问 的 远程 接口 遵循 标准 统一 的 
HTTP 接口 ， 却 需要 使 用 多 个 行为 各 异 的 客户 端 程序 库 ， 简 直 能 令 人 抓 狂 。 
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糟糕 的 是 ， 很 多 这 种 程序 库 是 全 有 或 全 无 的 选择 。 你 要 么 使 用 原始 的 HITP， 要 么 全 都 使 
用 API。 通 常 ， 你 无 法 访问 封装 库 发 送 的 HITP 请 求 ， 进 行 任何 细微 的 修改 。 响 应 也 是 一 
BE: 如 果 客 户 端 程序 库 不 提供 响应 中 的 某 些 部 分 ， 你 就 没有 办 法 获得 这 些 信 息 。 这 通常 意 
味 着 ， 如 果 服 务 器 端的 API 进行 了 细微 的 修改 ， 那 么 你 必须 改 用 客户 端 程序 库 的 新 版 本 ， 
或 者 至 少 在 升级 之 前 无 法 使 用 API 的 新 功能 。 


5. 不 适合 超 媒 体 

超 媒体 驱动 的 API 提供 的 资源 是 动态 的 。 为 这 种 API 创建 API 封装 程序 难度 特别 大 。 你 没 
有 办 法 定义 一 个 类 ， 有 了 时 包含 方法 ， 有 了 时 又 不 包含 。 我 相信 ， 超 媒体 驱动 API 之 所 以 特别 
少见 ， 原 因 之 一 就 是 大 多 数 人 找 不 到 在 客户 端 使 用 超 媒 体 API 的 简便 方法 。 


















































超 媒 体 API 的 真正 不 同 之 处 在 于 ，API 提供 的 分 布 式 功能 是 以 一 段 数 据 的 形式 传递 给 客户 
端的 。 这 些 功能 表现 为 返回 的 资源 表示 中 的 租 入 连接 。 把 函数 当 作 数据 进行 操作 并 不 是 一 
个 新 的 概念 ， 但 是 ， 在 超 媒体 中 ， 我 们 把 链接 看 作 代表 远程 调用 的 一 段 数据 。 

在 下 一 节 中 ， 我 们 要 讨论 构建 客户 端 程序 库 的 另 一 种 方式 ， 将 链接 提升 为 第 一 类 概念 ， 可 
以 用 于 对 API 进行 远程 调用 。 这 种 方式 更 适合 用 于 超 媒体 驱动 的 API， 但 是 对 于 那些 没有 
遵循 REST 全 部 约束 的 API， 使 用 这 种 方式 也 可 以 非常 高 效 地 进行 访问 。 


9.1.2 ”链接 用 作 函 数 

一 个 链接 中 最 重要 的 部 分 是 URL。 但 是 ，URL 本 身 只 是 一 个 标识 符 ， 需 要 由 服务 器 解释 。 
这 个 标识 符 的 重要 性 由 链接 关系 类 型 (link relation type) 决定 。 如 果 不 理 解 一 个 链接 的 用 
途 ， 客 户 端 应 用 程序 就 很 难 使 用 这 个 链接 。 





























让 我 们 再 来 看 stylesheet 链接 关系 。stylesheet 的 链接 关系 规范 只 是 简单 地 说 这 种 链接 
“指向 一 个 样式 表 ”。 但 是 ，Web 浏览 器 具有 明确 的 逻辑 ， 会 自动 使 用 GET 方法 对 这 种 类 型 
的 链接 进行 解 引 用 ， 使 用 返回 的 资源 表示 对 内 容 文档 进行 显示 上 的 修改 。 客 户 端 可 以 对 特 
定 的 链接 关系 类 型 选择 使 用 任何 逻辑 。 


绝 大 多 数 的 链接 关系 类 型 都 不 指定 客户 端 应 该 如 何 处 理 一 个 响应 。 但 是 ， 有 些 关 系 对 于 如 
何 激 活 链接 ， 声 明了 某 种 支持 的 协议 。 例 如 : search, oauth2-token 和 oauth2-authorize。 



































将 链接 实现 为 一 个 类 ， 我 们 可 以 在 其 中 包含 创建 一 个 HTTP 请 求 ， 以 及 在 某 些 情况 下 处 理 
返回 响应 所 需 的 操作 。 





var tokenLink = new OAuth2TokenLink 


Target = new Uri("https://login. Live.com/oauth20_token.srf"), 
RedirectUri = new Uri("https://login. Live.com/oauth20_desktop.srf"), 
ClientId = "000000007COB306F", 

ClientSecret = "LSKOqUbIV5HSPHt20M9Z4Ay219Mf -DNA" , 
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GrantType = "authorization_code", 
AuthorizationCode = "3eab54b1-86fa-4596-ce5e-91cb4e55bbd3" 
}; 
var client = new HttpClient(); 
var response = await client.SendAsync(tokenLink.CreateRequest()); 


var body = await response.Content.ReadAsStringAsync(); 


if (response. IsSuccessStatusCode) 


{ 

var token = OAuth2TokenLink.ParseTokenBody(body) ; 
} 
else 
{ 

var error = OAuth2TokenLink.ParseErrorBody(body) ; 
} 


在 这 个 例子 中 ，0Auth2TokenLink 代表 指向 一 个 OAuth 令 牌 生成 资源 的 链接 。 这 个 链接 类 
提供 了 发 起 请 求 所 需 的 所 有 参数 。 这 些 参数 可 以 定义 为 NET 中 任意 适合 的 类 型 。 将 这 些 
信息 转换 成 HTTP 请 求 所 需 格式 ， 其 中 的 实现 细 证 都 被 抽象 了 出 去 。 














通过 调用 CreateRequest，0Auth2TokenLink 类 创建 了 一 个 HttpRequestMessage 实例 ， 其 
H&H POST, Content 属性 为 填充 了 所 需 全 部 参数 的 FormEncodedUrlContent 实例 。 随 
后 这 个 HttpRequestMessage 实例 可 以 像 任何 其 他 请 求 一 样 使 用 。 我 们 可 以 重用 带 有 通常 
DefaultRequestHeaders 和 MessageHandlers 的 标准 HttpCLient， 发 送 这 个 请 求 。 











一 旦 我 们 获得 了 HttpResponseMessage， 就 可 以 使 用 OAuth2TokenLink 解析 响应 正文 。 采 用 
这 种 方式 ， 我 们 将 所 有 的 链接 语义 都 封装 在 了 链接 类 中 ， 而 且 程 序 库 中 的 类 也 不 必 处 理发 
送 请 求 的 机 制 。 


1. 服务 反 模 式 
客户 端 封装 库 的 开发 者 通常 会 定义 一 个 服务 类 ， 提 供 一 组 对 应 于 远程 资源 的 方法 。 例 如 ; 
如 果 我 们 要 为 Issue API 创建 一 个 封装 库 ， 代 码 可 能 如 下 所 示 : 























public class IssueApi { 


public Issue GetIssue(int id) {...} 

public Issue CreateIssue(IssueDto issueInfo) {...} 
public List<Issue> GetOpenIssues() {...} 

public List<Issue> GetMyIssues 

(int userId) {...} 


} 


var issueApi = new IssueApi("http://example.org/issueApi"); 
var issue = issueApi.GetIssue(77); 


List<Issues> openIssues = issueApi.GetOpenIssues(); 


这 种 实现 方式 有 一 个 问题 : 整个 API 是 由 服务 API 类 决定 的 。 可 用 的 资产、 返回 类 型 和 参 








AR 
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数 都 定义 在 客户 端 程序 库 中 。 





我 们 可 以 使 用 IssueLink 和 IssuesLink 类 实现 同样 的 功能 。 要 访问 这 些 资源 ， 还 有 更 为 通 
用 的 方法 ， 但 是 为 了 简化 讨论 ， 我 们 只 考虑 IssueLink 和 IssuesLink, 








为 了 访问 问题 和 问题 列表 ， 我 们 可 以 使 用 如 下 代码 : 
var httpClient = new HttpClient(); 


var issueLink = new IssueLink() { 
Target = new Uri("http://example.org/issueApi/Issue/{id}"), 
Id = 77 

} 


var issue = issueLink.ParseResponse( 
await httpClient.SendAsync(issueLink.CreateRequest())); 


var issuesLink = new IssuesLink() { 
Target = new Uri("http://example.org/issueApi/OpenIssues" ) 


} 


List<Issues> issues = issuesLink.ParseResponse( 
await httpClient.SendAsync(issueLink.CreateRequest())); 


通过 确保 我 们 的 API 耦合 只 限于 链接 类 型 ， 而 非 具体 的 资源 ， 当 APL 添加 更 多 资源 (如 
/ClosedIssues, /CriticalIssues 和 /LateIssues) 时 ， 我 们 相信 IssueLink 还 能 够 正常 
TEs 


var httpClient = new HttpClient(); 


var closedIssuesLink = new IssuesLink { 
Target = new Uri("http://acme.org/issueApi/ClosedIssues"), 


Js 


List<Issues> closedIssues = issuesLink.ParseResponse( 
httpClient.SendAsync(closedIssuesLink.CreateRequest())); 


var criticalIssuesLink = new IssuesLink { 
Target = new Uri("http://acme.org/issueApi/CriticalIssues"), 


J; 


List<Issues> criticalIssues = issuesLink.ParseResponse( 
httpClient.SendAsync(criticalIssuesLink.CreateRequest())); 


var lateIssuesLink = new IssuesLink { 
Target = new Uri("http://acme.org/issueApi/LateIssues"), 


J 


List<Issues> lateIssues = issuesLink.ParseResponse( 
httpClient.SendAsync(lateIssuesLink.CreateRequest())); 


上 面 这 些 请 求 的 语义 都 是 相同 的 ， 都 是 一 个 CET 请 求 ， 返 回 包含 一 列 问题 的 媒体 类 型 。 虽 
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然 每 个 链接 返回 不 同 的 问题 子 集 ， 但 是 这 并 不 影响 链接 的 语义 。 在 封装 API 中 ， 如 果 要 实 
现 同 样 的 操作 ， 就 必须 在 客户 端 程序 库 中 创建 新 的 方法 ， 以 提供 这 些 资源 。API 的 使 用 者 
必须 等 待 客户 端 程序 库 的 新 版 本 发 布 ， 并 且 要 更 新 客户 端 代码 ， 然 后 才能 访问 这 些 新 资源 。 


为 了 规避 难以 向 客户 端 提供 新 资源 的 问题 ， 人 们 经 常 试图 在 API 中 提供 复杂 的 查询 功能 。 
这 种 做 法 不 仅 会 造成 对 查询 语法 的 看 合 ， 而 且 还 会 带 来 另外 一 个 问题 ， 这 室 容 儿 个 查询 参 
数 可 能 打开 大 量 的 潜在 资源 ， 而 这 些 资源 中 的 一 些 生成 代价 很 高 。 很 多 API 提供 者 已 经 开 
台 意 识 到 ， 向 第 三 方 提 供 任意 查询 的 功能 很 难 平衡 得 失 。 一 种 更 容易 控制 的 方式 是 ， 提 供 
少量 高 度 优化 的 资源 ， 支 持 大 部 分 的 功能 。 但 是 ， 在 API 中 添加 新 资源 以 满足 新 需求 ， 这 
种 能 力 依 然 是 至 关 重要 的 。 


2. 反 序列 化 链接 
一 旦 你 接受 了 在 资源 表示 中 伐 入 链接 的 概念 ， 还 可 以 实现 资源 表示 的 反 序列 化 ， 自 动 生成 
链接 实例 ， 你 要 做 的 只 是 从 资源 表示 的 对 象 模型 中 获取 这 些 链 接 。 


当 使 用 的 链接 关系 没有 专门 的 媒体 类 型 时 ， 资 源 表 示 的 反 序列 化 代码 需要 使 用 某 种 形式 的 
链接 工厂， 以 创建 正确 类 型 的 链接 。 你 可 以 用 链接 关系 值 查询 一 个 类 型 字典 表 ， 确 定 需要 
实例 化 的 正确 类 型 。 


3. 分 离 请 求 和 响应 

调用 封装 类 方法 和 使 用 链接 发 起 请 求 ， 二 者 最 大 的 区 别 之 一 是 请 求 和 响应 的 分 离 。 使 用 链 
接 发 起 请 求 分 为 清晰 的 两 步 : 首先 ， 创 建 请 求 ， 发 送 给 源 服务 器 ， 随 后 ， 可 选 的 ， 将 响应 
传递 给 链接 进行 处 理 。 将 请 求 和 响应 分 开具 有 若干 好 处 。 发 起 HTTP 请 求 相 对 来 说 是 非常 
重大 的 操作 ， 因 此 ， 所 有 使 用 HttpCLient 的 HTTP 请 求 都 是 异步 的 。 异 步 操作 的 请 求 和 响 
应 代码 是 分 开 的。 最 近 版 本 的 C# 和 .NET 可 以 从 语法 上 隐藏 这 种 分 隔 ， 但 是 在 根本 上 ， 这 
种 分 离 依然 是 存在 的 。 将 链接 的 请 求 和 响应 处 理 分 开 ， 更 加 符合 这 种 异步 操作 的 特点 。 


使 用 封装 API 时 ， 我 们 认为 HITP 请 求 将 在 封装 类 方法 中 进行 完全 的 处 理 。 这 意味 着 ， 访 
问 一 个 资源 的 每 个 方法 都 必须 处 理 API 返回 的 状态 码 中 所 有 不 是 2XX 的 响应 。 封 装 程序 库 
必须 决定 如 何 处 理 3XX 重 定向 、401 Unauthroized 响应 和 503 Server Unavailable 响应 。 
在 使 用 多 个 API 时 ， 因 为 不 同 的 封装 API 处 理 这 些 响 应 的 方式 可 能 会 不 同 ， 会 使 事情 变 得 
更 为 复杂 。 


使 用 链接 类 ， 你 可 以 先 检查 不 是 2XX 的 状态 ， 然 后 再 将 响应 传递 给 链接 进行 处 理 。 这 样 可 
以 比较 容易 对 重 定向 和 错误 状态 进行 一 致 的 、 集 中 的 处 理 。 















































var httpClient = new HttpClient(); 


var issueLink = new IssueLink() { 
Target = new Uri("http://example.org/issueApi/Issue/{id}"), 
Id = 77 

} 
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var response = await httpClient.SendAsync(issueLink.CreateRequest()); 


if (response.IsSuccessStatusCode) { 
var issue = issueLink.ParseResponse(response) ; 
} else { 
GlobalNonSuccessResponseHandler .Handle( response) 


} 


HttpClient 类 具有 可 扩展 的 处 理 程序 管道 ， 可 以 更 容易 、 更 清晰 地 添加 这 种 横 切 处 理 程序 
(cross-cutting handler)。 在 第 14 章 中 ,我们 将 更 深入 地 介绍 如 何 利 用 分 离 的 请 求 和 响应 处 
理 ， 构 建 响应 式 的 客户 端 。 


这 里 的 重点 是 ， 在 横 切 关注 点 的 处 理 上 ， 客 户 端 应 用 程序 的 开发 者 不 再 受到 API 封装 程序 
库 的 设计 限制 。API 提供 者 可 以 提供 强 类 型 的 链接 ， 只 关注 与 其 API 相关 的 代码 实现 ， 而 
将 通用 的 HTTP 关注 点 留 给 通用 的 HTTP 代码 库 处 理 。 
































4. 链接 书签 

使 用 链接 生成 HttpRequestMessage 实例 ， 有 一 个 附带 的 好 处 是 可 以 很 方便 地 重复 发 起 请 求 。 
一 个 HttpRequestMessage 实例 只 能 用 于 发 送 一 个 HTTP 请 求 ， 而 链接 对 象 可 以 创建 配置 一 
次 ， 用 于 发 送 多 个 请 求 。 一 个 链接 对 象 也 可 以 修改 一 个 或 多 个 参数 ， 创 建 一 个 新 的 请 求 。 


链接 也 可 以 作为 客户 端 状态 的 一 部 分 进行 存储 ， 当 作 某 种 临时 书签 。 当 开发 者 首次 接触 超 
媒体 API 的 时 候 ， 经 常 产 生 的 一 个 不 满 和 担心 是 ， 需 要 发 出 多 个 请 求 ， 才 能 从 API 的 根 资 
源 访问 到 所 需 的 资源 。 通 过 保存 链接 书签 ， 客 户 端 可 以 缓存 链接 进行 重用 ， 将 额外 的 往复 
通信 减 到 最 少 。 

















假设 我 们 要 给 Issue API 的 根 增加 一 个 json-home 文档 ， 内 容 可 能 如 下 所 示 : 





{ 
"resources": { 
"http: //example.org/rel/issue": { 
"href-template": "/example.org/issueApi/issue/{id}", 
"href-vars": { 
"id": "http://example.org/param/issueid" 
} 
Js 
"http://example.org/rel/issues": { 
"href": "/issueApi/issues", 
} 
"http://eample.org/rel/issueprocessor" : { 
"href-template" : "issues/{id}/issueprocessor", 
"href-vars": { 
"id": "http://example.org/param/issueid" 
} 
} 
} 
} 
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对 API 根 资源 的 初始 请 求 可 以 获取 这 个 主 文档 ， 解 析 链 接 ， 创 建 链接 对 象 ， 然 后 将 链接 对 
象 存储 在 一 个 全 局 可 访问 的 字典 中 。 例 如 : 


var httpClient = new HttpClient(); 


var homeLink = new HomeLink() { 
Target = new Uri("http://example.org/issueApi" ) 
} 


var response = await httpClient.GetAsync(homeLink.CreateRequest()); 
var homedoc = homeLink.ParseHomeDocument(response, LinkFactory); 
GlobalLinks = homeDoc.GetResourcesAsDictionary(); 


var issueLink = GlobalLinks["http://example.org/rel/issue"]; 


在 这 个 简化 的 示例 中 ， 我 们 使 用 一 个 根 文档 ， 将 发 现 的 所 有 链接 填充 到 GlobalLinks 字典 
中 。 这 有 段 代码 只 在 客户 端 应 用 程序 启动 时 运行 一 次 ， 支 持 超 媒体 的 开销 ， 就 是 客户 端 程序 
每 运行 一 次 都 需要 一 次 额外 的 往复 通信 。 


将 应 用 程序 所 有 的 链接 都 存储 在 一 个 根 文档 中 ， 并 不 是 超 媒体 API 的 最 佳 实践 ， 因 为 这 种 
做 法 不 能 根据 上 下 文 判断 哪些 链接 可 用 。 但 是 ， 每 个 API 中 都 会 有 一 些 链 接 是 在 根 文 档 中 
提供 的 。 其 他 的 链接 可 以 通过 系统 中 的 其 他 资源 发 现 得 到 ， 这 些 链 接 也 可 以 保存 为 书签 。 


不 存在 一 种 适合 所 有 Web API 的 解决 方法 。 一 些 技术 适用 于 某 些 情况 ， 但 并 不 一 定 适合 所 
有 情况 。 我 们 的 目的 是 进行 探索 ,研究 什么 技术 可 能 解决 追求 可 演化 性 带 来 的 挑战 。 


创建 一 个 发 现 资源 的 根 文档 ， 将 所 有 链接 进行 全 局 缓存 ， 这 种 做 法 虽然 有 其 缺点 ， 但 是 可 
演化 性 远 好 于 在 客户 端 程序 库 中 硬 编码 URI， 而 且 实现 起 来 非常 简单 。 
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使 用 链接 对 交互 语义 进行 封装 ， 提 供 一 个 间接 层 ， 使 服务 器 可 以 演化 其 URI 空间 ， 这 些 帮 
助 我 们 向 消除 分 布 组 件 之 间 耦 合 的 目标 迈进 了 一 大 步 。 


但 是 ， 客 户 端 和 服务 器 还 是 会 由 访问 多 个 资源 的 交互 协议 联系 在 一 起 。 如 果 一 个 客户 端的 
代码 逻辑 为 :获取 资源 A， 获 取 资 源 B， 展 示 信 息 ， 得 到 一 些 输入 ， 然 后 把 结果 发 送 给 资 
源 C。 你 必须 修改 客户 端 才 能 改变 这 个 工作 流 。 如 果 服 务 器 在 资源 A 和 B 之 间 加 入 一 个 额 
外 的 资源 A'， 客 户 端 不 可 能 自动 使 用 这 个 新 资源 。 然 而 ， 如 果 资 源 A 包含 一 个 rel='next' 
的 链接 ， 那 么 客户 端 可 以 跟随 这 个 netx 链接 ， 直 到 获得 指向 资源 C 的 链接 。 如 此 一 来 ， 
服务 器 可 以 选择 添加 或 删除 中 间 步 又， 而 不 影响 客户 端的 正常 工作 。 
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9.2.1 AAA 

将 应 用 程序 的 工作 流转 移 到 服务 器 端 ， 形 成 了 这 样 一 种 客户 端 架 构 : 对 于 如 何 根据 宣称 的 
媒体 类 型 处 理 单独 的 资源 表示 ， 客 户 端 表现 得 极为 智能 ， 并 能 基于 链接 关系 的 语义 实现 复 
杂 的 交互 机 制 。 但 是 ， 用 户 代 理 对 于 自己 的 行为 在 整个 应 用 程序 中 的 作用 一 无 所 知 。 这 一 
特点 简化 了 客户 端 代码 ， 同 时 也 有 助 于 系统 随 着 时 间 发 生变 化 。 使 用 同一 个 Web 浏览 器 客 
户 端 的 用 户 ， 可 以 先 执行 银行 交易 ， 又 可 以 接着 浏览 菜谱 网 站 ， 寻 找 晚餐 灵感 。 


很 多 时 候 ， 客 户 端 应 用 程序 可 能 不 希望 将 工作 流 控制 完全 移交 给 服务 器 。 也 许 ， 一 个 客户 
端 实际 上 与 多 个 彼此 无 关 的 服务 进行 交互 ， 或 者 客户 端 想 实现 服务 器 开发 者 没有 考虑 到 的 
功能 。 即 便 是 在 这 些 情况 下 ， 适 当 放 弃 一 些 工 作 流 控制 也 会 给 客户 端 带 来 益处 。 


要 让 服务 器 接管 一 些 工作 流 的 职责 ， 一 个 方法 是 用 应 用 程序 域 的 目标 来 定义 客户 端 行为 ， 
而 不 是 用 HTTP 交互 来 定义 。 在 传统 的 客户 端 应 用 程序 中 ， 应 用 程序 方法 和 HTTP 请 求 经 
常 是 一 对 一 的 关系 。 但 是 ， 实 际 满足 用 户 的 需求 可 能 需要 多 个 HTTP 请 求 。 如 果 对 实现 目 
标 所 需 的 交互 进行 封装 ， 我 们 构建 的 工作 单元 在 遇 到 变更 时 适应 性 就 会 更 好 。 


假设 有 办 法 对 实现 用 户 目标 的 程序 进行 封装 ， 我 们 会 想 使 该 目标 的 实现 变 得 更 加 灵活 。 今 
天 ， 实 现 用 户 目标 也 许 需 要 两 个 HTTP 请 求 ， 但 是 将 来 当 服务 器 发 现 很 多 用 户 都 会 调用 这 
个 特殊 的 请 求 序列 时 ， 可 能 会 优化 API， 使 其 只 用 一 个 请 求 就 实现 目标 。 在 理想 情况 下 ， 
客户 端 应 该 可 以 不 进行 修改 就 享受 到 这 个 优化 。 


























为 了 获得 这 样 的 灵活 性 ， 我 们 需要 对 HTTP 响应 做 出 反应 ， 而 不 是 预期 收 到 什么 响应 。 标 
准 的 HTTP 客户 端 程序 库 已 经 在 一 定 程度 上 采取 了 这 种 做 法 。 设 想 一 个 场景 ， 客 户 端 从 资 
源 A 获取 一 个 表示 。 服 务 器 API 有 一 些 资 源 需 要 认证 ， 其 他 资源 不 需要 认证 。HttpCLient 
持 有 一 组 凭据 ， 但 是 在 访问 资源 A 时 并 不 使 用 这 些 凭据 ， 因 为 资源 A 不 需要 认证 。 由 于 
某 些 外 部 因素 ， 服 务 器 决定 改变 行为 ， 要 求 对 资源 A 进行 认证 。 当 客户 端 试 图 获取 资源 A 
时 ， 就 会 收 到 一 个 401 error 和 一 个 www-authenticate 标 头 。 客 户 端 明 白 了 问题 所 在 ， 对 
此 做 出 反应 ， 使 用 凭据 重新 向 资源 A 发 送 请 求 。 对 于 发 起 HTTP 请 求 的 客户 端 程序 来 说 ， 
这 一 系列 交互 的 发 生 可 能 都 是 完全 透明 的 。 


有 些 HTTP 客户 端 在 收 到 重 定向 (3XX) 状态 码 时 也 会 做 出 同样 的 反应 。HTTP 程序 库 负 责 
将 单个 请 求 转换 成 多 个 请 求 ， 以 实现 原本 的 目标 。 





















































把 同样 的 想法 在 应 用 程序 域 中 实现 ， 我 们 就 可 以 获得 类 似 的 灵活 性 ， 处 理 很 多 以 前 认为 是 
破坏 性 的 变更 。 





请 看 下 面 的 代码 片段 ， 这 可 能 是 一 个 客户 端 应 用 程序 的 一 部 分 : 
public void SelectIssue(IssueLink issueLink) { 


var response = await _httpClient.SendAsync(issueLink.CreateRequest()); 
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var issue = issueLink.ParseResponse(response) ; 


var form = new IssueForm(); 
form.Display(issue); 


} 
再 请 看 下 面 的 代码 : 
public void Select(Link aLink) { 


var response = await _httpClient.SendAsync(aLink.CreateRequest()); 
List<Issue> issues = new List<Issue>(); 


switch(response.Content.Headers.ContentType.MediaType) { 


case "application/collection+json" : 
LoadIssues(issues, response.Content) 
break; 


case "“application/issuet+json" : 
issues .Add(issueLink.ParseResponse(response) ); 
break; 


} 


foreach(var issues in issues) { 
var form = IssueFormFactory.CreateIssueForm(); 
form.Display(issue); 


} 


这 是 一 个 虚构 的 示例 ， 简 单 演示 可 能 的 实现 。 在 这 个 示例 中 ， 我 们 认识 到 请 求 可 能 返回 不 
同 的 媒体 类 型 。 如 果 请 求 的 链接 只 返回 一 个 问题 ， 我 们 就 直接 显示 这 个 问题 ， 如 果 请 求 返 
回 一 个 问题 集合 ， 那 么 就 搜索 问题 链接 ， 加 载 整个 问题 集合 ， 全 部 予以 显示 。 





























如 果 你 能 够 实现 下 面 的 代码 ， 客 户 端 应 用 程序 将 会 变 得 非常 有 意思 : 











public void Select(Link aLink) { 


var response = await _httpClient.SendAsync(aLink.CreateRequest()); 
GlobalHandler .HandleResponse(aLink, response); 


} 


使 用 这 段 代码 中 的 方法 ， 客 户 端 应 用 程序 和 用 于 获取 响应 的 链接 ， 以 及 用 户 处 理 响应 消息 
的 具体 响应 消息 ， 这 三 者 中 的 上 下 文 是 一 样 多 的 。 这 种 方法 实现 了 工作 流 去 炮 的 终极 目 
标 ， 和 Web 浏览 器 的 工作 方式 非常 类 似 。 


1. 处 理 所 有 版 本 

当 服务 器 对 其 API 进行 优化 时 ， 客 户 端 很 有 可 能 不 具备 利用 这 些 优化 的 必要 知识 。 只 要 服 
务 器 仍然 保留 未 优化 的 交互 机 制 ， 客 户 端 就 能 继续 工作 ， 浑 然 不 知 还 有 更 快 的 方法 可 用 。 
在 客户 端的 下 一 个 版 本 中 ， 可 以 引入 代码 ， 一 旦 存在 优化 方式 就 加 以 利用 。 关 键 在 于 客户 
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端 要 进行 必要 的 功能 检测 ， 判 断 功能 是 否 可 用 。 如 果 服 务 器 API 只 有 一 个 实例 ， 如 Twitter 
或 Facebook， 这 可 能 并 不 是 个 问题 。 但 是 ， 如 果 为 如 WordPress 这 样 的 产品 开发 客户 端 程 
序 库 ， 你 就 不 能 保证 服务 器 API 的 哪些 功能 是 可 用 的 。 


将 反应 性 行为 与 功能 检测 相 结合 ， 客 户 端 和 服务 器 就 可 以 持续 合作 ， 无 需 进行 版 本 号 协 
调 。 这 种 功能 应 该 从 一 开始 就 进行 计划 ， 不 太 容易 添加 到 一 个 已 经 存在 的 客户 端 中 。 








2. 变更 不 可 避免 
在 不 同 的 情况 下 ， 服 务 器 可 能 做 出 客户 端 可 适应 的 变更 。 我 们 将 讨论 一 些 经 常 发 生 的 
情况 。 











通过 分 析 客 户 端 访问 API 的 路 径 ， 服 务 器 可 能 决定 引入 一 个 快捷 链接 ， 绕 过 一 些 中 间 表 示 。 
有 时， 服务 器 会 给 URI 模板 添加 一 个 参数 ， 实 现 这 种 快捷 访问 。 客 户 端 可 以 通过 链接 关系 
寻找 这 种 快捷 链接 ， 如 果 快 捷 链接 不 存在 ， 客 户 端 可 以 继续 使 用 原来 的 方式 进行 访问 。 


API 可 能 引入 效率 更 高 ， 或 者 携带 更 多 语义 的 新 的 表示 。 新 的 媒体 类 型 总 是 不 断 出 现 。 如 
果 一 个 客户 端 实现 支持 这 种 新 格式 ， 就 可 以 在 请 求 的 Accept 标 头 中 加 入 这 个 类 型 ， 告 诉 服 
务 器 自己 支持 这 种 新 格式 。 为 了 与 旧版 本 的 API 兼容 ， 客 户 端 仍然 需要 支持 旧 格式 。 假 设 
客户 端 在 设计 时 就 知道 服务 器 可 能 返回 多 种 格式 ， 通 常 很 容易 就 能 实现 这 种 功能 。 


在 设计 表示 时 ， 服 务 器 需要 决定 咎 入 相关 资源 的 信息 ， 或 是 提供 相关 资源 的 链接 。 有 了 时， 
服务 器 需要 修改 已 经 做 出 的 决定 。 如 果 一 个 资源 表示 规模 过 大 ， 租 入 资源 可 能 需要 替换 为 
链接 。 如 果 客 户 端 总 是 访问 某 些 相关 资源 的 链接 ， 那 么 在 返回 时 筷 入 这 些 内 容 可 能 效率 会 
更 高 。 如 果 客 户 端 设计 为 在 需要 时 可 以 透明 地 幅 入 链接 资源 ， 那 么 服务 器 就 可 以 修改 资源 
表示 ， 而 不 会 破坏 客户 端 。 




















人 工 驱 动 (human-driven) 的 客户 端 经 常 需要 向 用 户 展示 一 组 可 用 的 资源 链接 。 在 这 种 情 
况 下 ， 遍 历 页 面 上 的 所 有 和 链接 并 未 一 展示 ， 比 将 静态 UI 元 素 绑 定 到 已 知 链接 要 好 。 采 用 
动态 构建 UI 的 方法 ， 当 服务 器 可 以 添加 资源 链接 时 ， 客 户 端 能 够 自动 访问 这 些 链 接 。 








如 果 资 源 链 接 移 除 ， 即 便 这 些 链接 绑 定 到 固定 的 Ul 元素， 客户 端 也 可 以 使 这 些 元 素 失 效 ， 
说 明 相 应 的 资源 不 可 用 。 客 户 端 不 应 该 仅 因 一 个 链接 不 存在 就 不 工作 。 有 时 ， 移 除 一 个 链 
接 可 能 使 用 户 无 法 完成 一 个 特定 功能 ， 但 我 们 可 以 认为 其 他 的 功能 依然 可 用 。 对 于 客户 端 
来 说 ， 移 除 一 个 功能 不 应 该 是 破坏 性 的 变更 。 








由 于 URI 空间 重组 ,或 者 将 资源 移 到 新 主机 上 以 均衡 负载 ， 服 务 器 可 能 会 改变 资源 到 新 的 
URI。 客 户 端 应 该 能 够 透明 地 处 理由 此 导致 的 重 定向 请 求 。 


服务 器 每 次 向 链接 添加 新 的 查询 参数 时 ， 都 应 该 给 这 些 新 增 的 参数 提供 默认 值 。 如 果 服 务 
器 没有 给 新 增 参 数 提供 默认 值 ， 就 会 造成 破坏 性 变更 ， 在 这 种 情况 下 ， 服 务 器 应 该 添加 一 
个 新 的 链接 和 链接 类 型 ， 定 义 这 个 新 的 需求 。 客 户 端 应 用 程序 应 该 能 够 继续 安全 地 使 用 链 
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接 ， 无 需 指 定 新 的 参数 。 客 户 端的 未 来 更 新 应 该 能 够 使 用 这 个 新 参数 。 


如 果 服 务 器 发 现 不 再 需要 标识 资源 的 一 个 参数 ， 就 应 该 更 新 URI 模板 ， 不 再 包含 这 个 参数 
值 。 当 客户 端 试 图 设置 不 在 URI 模板 中 的 参数 时 ， 不 应 该 得 到 失败 结果 。 解 析 后 得 到 的 
URL 应 当 不 再 包含 已 经 移 除 的 参数 ， 否 则 服务 器 可 能 返回 状态 码 404, 








在 一 些 情况 下 ， 以 前 接受 GET 和 POST 方法 的 资源 可 能 会 进行 拆 分 ， 单 独创 建 一 个 资源 处 
AE POST 请 求 。 在 这 种 情况 下 ， 服 务 器 应 该 提供 另 一 个 链接 和 链接 关系 ， 并 实现 从 原 有 资源 
POST 的 重 定向 ， 以 处 理 过 渡 时 期 的 请 求 。 











4 











一 个 交互 序列 可 能 添加 新 的 步骤 。 在 这 种 情况 下 ， 服 务 右 可 以 将 新 步骤 中 的 一 个 链接 标记 
为 “默认 的 ”链接 。 在 不 知道 如 何 处 理 一 个 特定 表示 时 ， 客 户 端 应 该 设计 为 使 用 默认 链接 。 

















链接 提示 IETF 互联 网 草案 (参见 http://tools.ietf.org/html/draft-nottingham-link-hint-00) 引 
入 了 对 链接 使 用 “ 弃 用 ”(deprecated) 属性 进行 修饰 的 功能 。 这 个 属性 可 以 告知 客户 端 ， 
未 来 这 个 链接 不 再 受到 支持 。 除 此 之 外 ， 服 务 器 开发 者 应 该 记录 这 些 弃 用 链接 的 使 用 情 
况 ， 以 及 访问 这 个 资源 的 用 户 代理 。 基 于 这 些 信 息 ， 我 们 可 以 进行 离线 沟通 ， 敦 促 客 户 端 
开发 者 停止 使 用 这 些 弃 用 链接 。 














毫 无 疑问 ， 服 务 器 API 可 能 发 生 很 多 别 的 变更 情况 。 但 是 ， 这 些 例子 说 明 ，Web 架构 的 设 
计 方 式 使 得 客户 端 可 以 适应 这 些 变 更 。 如 果 我 们 不 再 费力 地 进行 客户 端 和 服务 器 的 版 本 兼 
容 管 理 ， 而 是 把 精力 放 在 处 理 API 的 可 能 变更 上 ， 那 么 就 可 以 更 快 进行 演化 ， 使 用 户 满意 
度 更 高 。 


9.2.2” 带 有 使 命 的 客户 端 

在 完全 由 人 工 驱 动 的 使 用 体验 (如 Web 浏览 器 ) 中 ， 交 互 模型 似乎 是 1:1 的 ， 其 实 并 非 如 
此 。 点 击 一 个 链接 会 加 载 一 个 HTML 页 面 ， 但 是 ,浏览 器 需要 加 载 链 接 的 样式 表 、 图 像 和 
脚本 。 只 有 当 所 有 这 些 请 求 都 完成 时 ， 展 示 页 面 的 目标 才 算是 完成 了 。 


要 描述 这 种 交互 的 封装 ， 我 能 想到 的 最 好 的 词 是 使 命 (mission)。 一 个 使 命 是 实现 一 个 客 
户 端 目标 所 需 的 请 求 和 响应 处 理 的 具体 实现 。 这 个 词 虽然 听 起 来 有 点 怪 ， 但 其 好 处 是 避免 
了 过 载 其 他 的 软件 术语 ， 如 任务 (task) 或 事务 (transaction)。 使 命 这 个 词 还 强调 了 目标 
的 重要 性 ， 而 非 具体 实现 的 细节 。 而 且 ， 人 们 经 常 将 HTTP 客户 端 称 为 代理 (agent), (È 
理 和 使 命 这 两 个 词 刚 好 相当 契合 。 


之 前 我 们 讨论 过 ， 链 接 关 系 可 以 用 于 标识 一 个 HITP 交互 的 语义 。 有 时 候 链 接 关 系 
也 能 传达 多 个 交互 的 需求 。 链 接 关 系 查 询 就 是 一 个 例子 。 一 个 查询 链接 指向 一 个 
OpenSearchDescription 文档 ， 该 文档 包含 了 关于 如 何 对 一 个 网 站 或 API 的 资源 进行 查询 的 
信息 。 最 简单 的 情况 下 ， 这 个 描述 文档 包含 一 个 URL 模板 ， 甚 中 的 {searchTerms} 符号 可 
以 替换 为 客户 端的 实际 查询 词 。 
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接 下 来 的 类 展示 了 如 何 创建 一 个 使 命 ， 对 一 系列 行为 进行 封装 : 得 到 OpenSearchDocument 
文档 、 解 释文 档 、 构 建 URL、 执 行 搜 索 和 返回 搜索 结果 。 


public class SearchMission 


{ 

private readonly HttpClient _httpClient; 

private readonly SearchLink _link; 

public SearchMission(HttpClient httpClient, SearchLink link) 

{ 
_httpClient = httpClient; 
_link = Link; 

} 

public async Task<HttpResponseMessage> GoAsync(string param) 

{ 
var openSearchDescription = await LoadOpenSearchDescription(); 
var link = openSearchDescription.Url; 
Link.SetParameter("searchTerms", param); 
return await _httpClient.SendAsync(link.CreateRequest()); 

} 

private async Task<OpenSearchDescription> LoadOpenSearchDescription( ) 

{ 
var response = await _httpClient.SendAsync(_link.CreateRequest()); 
var desc = await response.Content.ReadAsStreamAsync(); 
return new OpenSearchDescription( 

response.Content.Headers.ContentType, desc); 
} 
} 


这 个 使 命 类 自身 并 不 包括 解释 OpenSearchDescription 文档 的 细节 ， 这 部 分 由 媒体 类 型 解 
析 库 完成 。 使 命 只 关注 交互 的 协调 。 一 个 SearchMission 对 象 可 以 执行 多 个 搜索 。 


使 命 可 以 是 完全 与 HITP 资源 进行 的 基于 算法 的 交互 。 一 个 客户 端 应 用 程序 初始 化 一 个 使 
命 ， 然 后 持续 执行 ， 直 到 目标 实现 ， 或 者 使 命 失 败 。 使 命 可 以 成 为 一 个 重用 单元 ， 多 个 使 
命 可 以 结合 起 来 实现 更 大 的 目标 。 


使 命 也 可 以 是 交互 式 过 程 ， 在 一 些 交 互 之 后 ， 控 制 权 会 交还 给 人 工 用 户 ， 等 待 用 户 下 一 步 
的 指令 。 为 了 实现 这 个 功能 ， 使 命 需要 设计 有 接 到 用 户 界面 层 的 某 种 接口 。 使 命 必须 能 够 
使 用 这 个 接口 ， 将 当前 的 状态 展示 给 用 户 ， 并 接受 下 一 步 的 指令 。 这 个 用 户 界面 层 必 须 向 
人 类 提供 一 组 可 供 选 择 的 链接 ， 然 后 将 选中 的 链接 传 回 给 使 命 。 





























接 下 来 的 示例 包括 一 个 非常 简单 的 交互 式 使 命 ， 以 及 一 个 用 作 超 媒体 REPL (Read-Eval- 
Print Loop,“ 读 取 — 求 值 -输出 ”循环 ) 的 小 型 控制 台 应 用 程序 。 这 个 客户 端 应 用 程序 必 
须 使 用 一 个 链接 调用 使 命 的 GoAsync 方法 。 使 命 会 使 用 这 个 链接 ， 获 取 返 回 的 资源 表示 中 
的 任何 链接 。 一 个 简单 的 控制 台 应 用 程序 使 用 一 个 循环 ， 向 用 户 展示 初始 的 资源 表示 ， 并 
让 用 户 输入 另 一 个 链接 名 以 选择 使 用 这 个 链接 。 客 户 端 随后 会 要 求 使 命 使 用 这 个 链接 ， 并 
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重 解析 返回 的 链接 。 


public class ExploreMission 


{ 


} 


private readonly HttpClient _httpClient; 
public Link ContextLink { get; set; } 
public HttpContent CurrentRepresentation { get; set; } 


public Dictionary<string,Link> AvailableLinks { get; set; } 


public ExploreMission(HttpClient httpClient) 


{ 
_httpClient = httpClient; 
} 
public async Task GoAsync(Link link) 
{ 
var response = await _httpClient.SendAsync(link.CreateRequest()); 
if (response. IsSuccessStatusCode) 
{ 
ContextLink = Link; 
CurrentRepresentation = response.Content; 
AvailableLinks = ParseLinks(CurrentRepresentation) ; 
} 
} 


private Dictionary<string,Link> 
ParseLinks(HttpContent currentRepresentation) 


{ 
} 





// 根据 返回 的 媒体 类 型 解析 表示 中 的 链接 








static void Main(string[] args) 


{ 


} 


var exploreMission = new ExploreMission(new HttpClient()); 


var Link = new Link() {Target = new Uri("http://localhost:8080/")}; 
string input = null; 
while (input != "exit") 
{ 
expLoreMission.GoAsync( link) .Wait(); 
Console.WriteLine(exploreMission.CurrentRepresentation 
.ReadAsStringAsync().Result); 


Console.Write("Enter link relation to follow link : "); 
input = Console.ReadLine(); 
link = exploreMission.AvailableLinks[input]; 


一 个 有 实际 用 途 的 交互 式 客户 端 应 用 程序 所 做 的 工作 ， 显 然 要 比 这 个 示例 多 得 多 。 但 是 ， 


基本 前 提 是 一 样 的 : 使 用 一 个 链接 ， 更 新 客户 端 状 态 ， 向 用 户 展示 可 用 链接 ， 让 用 户 选择 





链接 ， 然 后 重复 这 一 过 程 。 
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9.2.3 客户 端 状 态 

客户 端 状 态 ， 也 经 常 称 为 客户 闯 应 用 程序 状态 ， 是 客户 端 应 用 程序 当前 跟踪 的 所 有 执行 使 命 
的 聚合 。 一 个 Web 浏览 器 包含 一 组 浏览 上 下 文 (browsing context， 参 见 http://www.w3.org/ 
TR/html5/browsers.html#windows)， 每 个 上 下 文 都 可 以 算是 一 个 顶级 使 命 (top-level mission) 。 

















如 果 构 建 的 客户 端 应 用 程序 框架 能 够 管理 一 组 活动 的 使 命 ， 你 就 可 以 把 问题 分 解 为 开发 面 
向 目标 的 使 命 ， 这 些 使 用 可 以 用 应 用 域 的 概念 来 描述 。 








虽然 客户 端 应 用 程序 状态 由 一 组 活动 使 命 组 成 ， 但 是 ， 每 个 使 命 在 执行 中 都 必须 谨慎 地 处 
理 状态 的 累积 。 


让 我 们 回 到 SearchMission 的 示例 ，SearchMission 对 象 可 以 保存 OpenSearchDescription 
对 象 的 一 个 引用 ， 进 行 重用 。 但 是 ， 一旦 客户 端 采 取 这 种 做 法 ， 就 接管 了 这 个 资源 表 
示 的 生存 期 的 所 有 权 ， 不 再 由 服务 器 控制 。 理 想 情 况 下 ， 服 务 器 会 提供 缓存 指令 ,使 
OpenSearchDescription 资源 表示 能 在 本 地 缓存 很 长 一 段 时 间 ， 重 复 使 用 SearchMission 对 
象 时 ， 请 求 描述 文档 就 不 会 引起 网 络 往复 通信 。 客 户 端 也 不 必 管 理 和 共享 SearchMission 
对 象 的 引用 ， 因 为 本 地 HTTP 缓存 是 持久 的 ， 客 户 端 应 用 程序 可 以 多 次 执行 重用 已 保存 的 


OpenSearchDocument 文档 。 



































对 于 很 多 人 来 说 ， 这 种 避免 保存 客户 端 状态 的 做 法 有 悖 常理 。 在 构建 客户 端 应 用 程序 时 ， 
传统 的 经 验 是 ， 如 有 果 我 们 保存 从 远程 服务 器 得 到 的 状态 ， 就 可 以 避免 在 之 后 发 起 网 络 往复 
通信 。 客 户 端 管理 资源 状态 生存 期 的 问题 是 ， 你 最 终 会 得 到 很 多 随意 的 缓存 机 制 。 通 常 ， 
这 些 客户 端 缓存 机 制 比 HTTP 提供 的 缓存 机 制 要 简易 得 多 。 客 户 端 通常 只 支持 两 种 生存 期 
的 范围 : 由 应 用 程序 生存 期 决定 的 全 局 范围 ， 以 及 某 种 工作 单元 范围 。 客 户 端 缓存 机 制 没 
有 缓存 过 期 的 概念 ， 当 然 也 没有 等 效 于 条 件 GET 的 操作 。 如 果 把 大 多 数 的 客户 端 缓 存 交 
给 HTTP 缓存 机 制 ， 客 户 端 代码 可 以 更 为 简单 ， 服务器 指定 资源 生存 期 ， 可 以 减少 一 至 
性 问题 ， 没 有 那么 多 上 下 文 信息 影响 客户 端 对 服务 器 响应 做 出 反应 ， 调 试 工作 也 会 变 得 
更 简单 。 



























































9.3 小 结 


虽然 Web 进入 我 们 的 生活 已 经 快 20 年 了 ， 但 是 ， 在 构建 适合 Web 架构 的 客户 端 方面 ， 我 
们 的 经 验 却 依然 十 分 有 限 。 真 正 的 Web 客户 端 主 要 局 限于 Web 浏览 器 、RSS 摘要 阅读 器 
和 网 络 爬 虫 。 拥 有 开发 其 中 任意 一 类 工具 经 验 的 开发 者 灾 灾 无 儿 。 最 近 开始 流行 的 单 页 应 
用 程序 (single-page application) 带 来 了 一 种 新 的 模式 ， 人 们 尝试 在 一 个 用 户 代理 内 部 构建 
一 个 用 户 代 理 ， 这 种 模式 具有 其 独特 的 挑战 。 


依赖 于 分 布 式 服务 的 本 地 “应 用 ”的 兴起 ， 使 人 们 对 构建 Web 客户 端 重新 产生 了 兴趣 。 第 
一 批 这 种 分 布 式 应 用 试图 复制 20 世纪 90 年 代 的 客户 端 / 服 务 器 架构 。 但 是 ， 要 构建 出 像 
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Web 浏览 器 一 样 ， 真 正 利 用 Web 功能 的 应 用 ， 我 们 需要 模拟 Web 浏览 器 的 一 些 架 构 特征 。 


使 用 本 章 中 讨论 的 技术 ， 开 发 者 构建 的 客户 端 将 会 更 加 持久 ， 更 少 出 错 ， 性 能 更 好 ， 对 网 
络 失 败 的 容忍 度 更 高 。 遗 憾 的 是 ， 时 至 今日 ， 只 有 很 少 的 支持 程序 库 能 帮助 我 们 使 用 这 些 
技术 。 构 建 能 够 演化 的 松 耦 合 客户 端 会 带 来 很 多 的 好 处 ， 随 着 更 多 的 开发 者 开始 理解 这 些 
好 处 ， 未 来 可 望 出 现 更 多 的 可 用 工具 。 














作为 实践 这 些 技 术 的 第 一 步 ， 当 你 编写 发 出 网 络 请 求 的 客户 端 代 码 时 ， 请 停 下 来 ， 想 一 
想 ， 然 后 问 自 己 : 如 果 事 情 按 照 预期 的 情况 发 生 ， 会 怎么 样 ， 如 有 果 事 情 不 按 预期 发 生 ， 又 
会 怎么 样 ， HTTP 能 怎样 帮助 我 处 理 这 些 情 况 。 
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HTTP 编 程 模 型 





J 


消息 ， 完 整 的 消息 ， 只 有 这 个 消息 。 


à 


本 章 将 介绍 新 的 NET 框架 HTTP 编程 模型 ， 这 个 编程 模型 是 ASP.NET Web API 和 新 的 客 
Puig HTTP 支持 (特别 是 HttpClient 类 ) 的 核心 。 这 个 模型 包含 在 NET 4.5 中 ， 但 是 也 
可 以 通过 NuGet 包 (http://www.nuget.org/packages/Microsoft.Net.Http/2.0.20710) 获得 .NET 
4.0 的 版 本 。 新 的 HTTP 编程 模型 定义 了 一 个 新 的 程序 集 一 一 System.Net.Http.dll， 对 主 
要 的 HTTP 概念 ( 即 请 求 和 响应 消息 、 标 头 以 及 正文 内 容 ) 进行 了 具有 类 型 地 编程 抽象 。 





新 的 HTTP 编程 模型 有 一 个 辅助 程序 集 System.Net.Http.Formatting.dLL， 其 中 引入 了 媒体 
类 型 格式 化 程序 的 概念 (第 13 章 将 对 此 进行 介绍 )， 以 及 一 些 工具 扩展 方法 和 定制 的 HTTP 
内 容 类 型 。System.Net.Http.Formatting.dLL 可 以 从 “Microsoft ASP.NET Web API Client 
Libraries”( 参 见 http://www.nuget.org/packages/Microsoft.AspNet.WebApi.Client) NuGet 包 下 
载 ， 源 代码 属于 ASP.NET 项 目 (参见 https://aspnetwebstack.codeplex.com/)。 虽 然 这 个 软件 
包 名 称 是 “客户 端 代码 库 ”， 但 实际 上 在 客户 端 和 服务 器 端 都 可 以 使 用 。 本 章 ， 我 们 将 描述 
System.Net.dLL fH System.Net.Http.Formatting. dll 的 功能 ， 并 不 特意 区 分 二 者 。 


























在 引入 这 个 新 模型 前 ，.NET 框架 已 经 包含 了 多 个 用 于 处 理 HTTP 概念 的 编程 模型 。 在 客 
户 端 ，System.Net.HttpWebRequest 类 可 以 用 于 初始 化 HTTP 请 求 ， 处 理 相关 的 响应 ， 在 
服务 器 端 ，System.Web.HttpContext 及 其 相关 类 (如 HttpRequest 和 HttpResponse) 用 在 
ASP.NET 上 下 文中 ， 代 表单 个 请 求 和 响应 。 在 服务 器 端 ， 还 有 System.Net.HttpListener 
Context 类 ， 用 在 自 托管 的 System.Net.HttpListenser 中 ,提供 对 HTTP 请 求 和 响应 对 象 
的 访问 。 
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遗憾 的 是 ， 所 有 这 些 编程 模型 都 存在 若干 问题 。 新 的 模型 ， 即 System.Net.Http 编程 模型 ， 
致力 于 解决 这 些 问 题 ， 具 有 如 下 特点 : 


。 在 客户 端 和 服务 器 端 使 用 同样 的 类 ， 

。 基于 新 的 TAP (Task Asynchronous Pattem， 任 务 异 步 模式 )， 而 非 旧 的 APM (Asynchronous 
Programming Model， 异 步 编 程 模型 )， 也 就 是 说 ， 可 以 使 用 .NET4.5 中 提供 的 async 和 await, 

。 易于 在 测试 场景 中 使 用 ，; 

。 对 HTTP 消息 的 表示 类 型 更 强 一 一 换 句 话说 ， 就 是 将 HTTP 标 头 值 表示 为 类 型 ， 而 不 是 

公 散 的 字符 串 字 典 ， 
。 更 加 忠于 HTTP 规范 ， 即 不 在 HTTP 协议 上 堆 加 不 同 的 抽象 层 ; 
。 将 较 新 的 版 本 打包 为 可 移植 的 类 库 ， 可 以 在 多 种 平台 上 使 用 。 


在 接 下 来 的 小 节 中 ， 随 着 我 们 更 详细 地 介绍 这 个 新 的 模型 ， 以 上 这 些 特 点 会 变 得 更 加 清 
上 晰 。 我 们 将 首先 介绍 表示 基础 HTTP 概念 (也 就 是 请 求 和 响应 消息 ) 的 类 型 ， 接 着 将 展示 
如 何 通过 一 组 具体 的 类 ， 对 请 求 和 响应 消息 以 及 内 容 标 头 进行 表示 和 处 理 ， 最 后 讨论 如 何 
As BOATS FAYE) EA RRAN. 














在 我 们 开始 之 前 ， 请 注意 : 旧 的 HTTP 编程 模型 仍 可 使 用 ， 并 继续 受到 支持 。 例 如 ，ASP. 
NET 管道 依然 基于 旧 的 System.Net.HttpNebRequest。 


10.1 消息 


第 1 章 介绍 过 ，HTTP 协议 的 工作 方式 是 在 客户 端 和 服务 器 之 间 交 换 请 求 和 响应 消息 。 很 
自然 地 ，HTTP 编程 模型 的 核心 就 是 消息 抽象 ， 表 示 为 两 个 具体 类 : HttpRequestMessage 
和 HttpResponseMessage。 这 两 个 类 位 于 新 的 System.Net.Http 命名 空间 ， 如 图 10-1 所 示 。 
HttpRequestMessage 和 HttpResponseMessage 都 包含 : 














。 一 个 起 始 线 (start line) ; 

。 一 列 标 头 字段 (header field) ; 

。 一 个 可 选 的 有 效 载荷 正文 (payload body). 

对 于 请 求 消息 ， 起 始 线 由 如 下 HttpRequestMessage 属性 表示 : 


。 请 求 的 方法 (an GET BY POST), 定义 了 这 个 请 求 的 目的 ， 
e RequestUri， 标 识 目 标 资 源 ; 
。 协议 版 本 Version (如 1.1)。 


对 于 响应 消息 ， 起 始 线 由 如 下 HttpResponseMessage 属性 表示 : 





。 协议 版 本 Version (如 1.1) ; 
。 请 求 的 状态 码 StatusCode (一 个 三 位 的 整数 )， 以 及 提示 信息 Reason Phrase 字符 串 。 
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图 10-1: HttpRequestMessage 和 HttpResponseMessage 类 


响应 消息 还 包含 一 个 RequestMessage 属性 ， 指 向 对 应 的 请 求 消息 。 











请 求 和 响应 消息 都 可 以 包含 一 个 可 选 的 消息 正文 ， 表示 为 Content 属性 。 在 10.3 市 中 ,我 
们 将 详细 介绍 消息 内 容 如 何 表 示 、 创 建 和 使 用 ， 还 将 描述 基于 HttpContent 的 类 层次 结构 。 


Hz 





这 两 种 消息 类 型 以 及 消息 内 容 ， 都 可 以 使 用 相应 的 标 头 ， 携 带 元 数据 。10.2 节 将 介绍 处 至 


这 些 标 头 的 编程 模型 。 
HttpRequestMessage 和 HttpResponseMessage 类 都 不 是 抽象 类 ， 可 以 在 用 户 代码 中 很 容易 地 


实例 化 ， 如 下 所 示 : 


[Fact] 
public void HttpRequestMessage_is_easy_to_instantiate() 


{ 


var request = new HttpRequestMessage( 


HttpMethod.Get, 
new Uri("http://www.tetf.org/rfc/rfc2616.txt")); 


Assert.Equal(HttpMethod.Get, request.Method) ; 
Assert. Equal( 
"http: //www.ietf.org/rfc/rfc2616.txt", 
request.RequestUri.ToString()); 
Assert.Equal(new Version(1,1), request.Version); 


207 





HTTP 编 程 模型 


[Fact] 
public void HttpResponseMessage_is_easy_to_instantiate() 


{ 
var response = new HttpResponseMessage(HttpStatusCode.OK) ; 
Assert.Equal(HttpStatusCode.OK, response. StatusCode) ; 
Assert.Equal(new Version(1,1), response.Version); 

} 


消息 类 很 容易 在 测试 场景 中 使 用 ， 与 其 他 用 于 表示 同样 概念 的 .NET 框架 类 形成 强烈 对 比 。 





e System.Web.HttpRequest 类 ， 在 ASP.NET 的 System.Web.HttpContext 中 表示 一 个 请 求 。 
这 个 类 有 公共 的 构造 函数 ， 但 是 只 能 由 基础 结构 使 用 。 
e System.Web.HttpRequestBase 类 ， 在 ASP.NET MVC 中 使 用 。 这 个 类 是 抽象 类 ， 无 法 直 
接 初 始 化 。 
e System.Net.HttpWebRequest 类 ， 用 于 在 客户 端 表示 HTTP 请 求 。 这 个 类 有 公共 的 构造 
函数 ， 但 是 构造 函数 都 已 过 时 ， 应 该 通过 WebRequest.Create 工厂 方法 进 和 实例 化 。 








HttpRequestMessage 和 HttpResponseMessage 类 都 只 表示 HTTP 消息 ， 并 不 包含 其 他 的 上 
下 文 属性 ， 因 此 既 可 用 于 客户 端 ， 又 可 用 于 服务 器 端 。 这 一 点 与 其 他 的 HTTP 类 不 同 ， 例 
如 ，ASP.NET 的 HttpRequest 类 包含 一 个 属性 ， 用 于 保存 服务 器 上 的 虚拟 应 用 程序 根 路 
径 ， 这 个 属性 对 客户 端 显然 并 不 适用 。 


HttpMethod 实例 包含 方法 字符 串 (如 GET 或 P05T)， 代 表 请 求 方法 。HttpMethod 类 还 包含 
一 组 静态 属性 ， 对 应 RFC 2616 中 定义 的 方法 。 











public class HttpMethod : IEquatable<HttpMethod> 
{ 

public string Method {get;} 

public HttpMethod(string method); 


public static HttpMethod Get {get;} 
public static HttpMethod Put {get;} 
public static HttpMethod Post {get;} 
public static HttpMethod Delete {get;} 
public static HttpMethod Head {get;} 
public static HttpMethod Options {get;} 
public static HttpMethod Trace {get;} 
} 


要 使 用 一 个 新 方法 ， 如 RFC 5789 中 定义 的 PATCH， 我 们 必须 明确 使 用 方法 字符 串 ， 对 
HttpMethod 进行 初始 化 ， 代 码 如 下 所 示 : 


[Fact] 
public async Task New_HTTP_methods_can_be_used() 
{ 
var request = new HttpRequestMessage( 
new HttpMethod("PATCH"), 





new Uri("http://www.tetf.org/rfc/rfc2616.txt")); 
using(var client = new HttpClient()) 


{ 


var resp = await client.SendAsync(request); 
Assert. Equal (HttpStatusCode.MethodNotALlowed, resp.StatusCode) ; 


} 
枚 举 类 型 HttpstatusCode 表示 啊 应 的 状态 码 ， 其 中 包含 了 HTTP 规范 定义 的 所 有 状态 码 


public enum HttpStatusCode 
{ 
Continue = 100, 
SwitchingProtocols = 101, 
OK = 200, 
Created = 201, 
Accepted = 202, 


MovedPermanently = 301, 
Found = 302, 

SeeOther = 303, 
NotModified = 304, 


BadRequest = 400, 
Unauthorized = 401, 


InternalServerError = 500, 
} 
我 们 也 可 以 把 整数 转换 为 HttpStatusCode 类 型 ， 得 到 新 的 状态 码 


[Fact] 
public void New_status_codes_can_also_be_used() 
{ 
var response = new HttpResponseMessage((HttpStatusCode) 418) 
{ 
ReasonPhrase = "I'm a teapot" 
J}; 


Assert.Equal(418, (int)response.StatusCode); 
} 


HttpRequestMessage 还 包含 一 个 Properties JRE: 


public IDictionary<string, Object> Properties { get; } 


当 消 息 在 服务 器 或 者 客户 端 本 地 进行 处 理 时 ，Properties 属性 用 于 保存 附加 的 消息 信息 。 
例如 ，Properties 属性 可 以 保存 处 理 栈 底层 (例如 消息 处 理 程序 ) 产生 的 信息 ， 供 上 层 使 
用 (例如 控制 器 )。 


Properties 属性 并 不 属于 任何 标准 的 HTTP 消息 ， 当 消息 进行 序列 化 ， 准 备 传输 时 ， 不 会 
(RA Properties 属性 。Properties 属性 只 是 一 个 通用 的 容器 ， 保 存 本 地 消息 属性 ， 例 如 : 
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与 接受 消息 的 连接 相关 的 客户 端 认证 ， 

。 将 消息 与 配置 路 由 进行 匹配 ， 得 到 的 路 由 数据 。 

这 些 属性 存储 在 一 个 字典 表 中 ， 对 应 于 字符 串 键 值 。HttpPropertyKeys 类 定义 了 一 组 
常用 的 键 。 通 常情 况 下 ， 这 些 消息 属性 可 以 通过 扩展 方法 访问 ， 如 System.Net.Http. 


HttpRequestMessageExtensions 类 中 定义 的 方法 。 








public static IHttpRouteData GetRouteData(this HttpRequestMessage request) 


{ 
if (request == null) 
throw System.Web.Http.Error.ArgumentNull("request"); 


else 
return HttpRequestMessageExtensions.GetProperty<IHttpRouteData>( 
request, HttpPropertyKeys.HttpRouteDataKey) ; 


} 
Web API v2 中 引入 的 HttpRequestContext 类 ， 也 是 由 底层 的 托管 层 附加 到 请 求 属性 ， 供 上 
层 使 用 的 信息 。 
public static HttpRequestContext 
GetRequestContext(this HttpRequestMessage request) 
{ 
return request.GetProperty<HttpRequestContext>( 
HttpPropertyKeys.RequestContextKey) ; 
} 


public static void 
SetRequestContext(this HttpRequestMessage request, 


HttpRequestContext context) 


{ 
request.Properties[HttpPropertyKeys.RequestContextKey] = context; 


} 
也 就 是 说 ，HttpRequestContext 类 将 一 组 属性 (例如: 客户 端 证 书 ， 或 者 请 求 者 的 身份 信 


息 ) 聚合 在 一 个 具有 类 型 的 模型 中 。 





public class HttpRequestContext 


{ 
public virtual X509Certificate2 ClientCertificate { get; set; } 
public virtual IPrincipal Principal { get; set; } 


ae 


10.2 标 头 


在 HTTP 中 ， 请 求 和 响应 消息 ， 以 及 消息 内 容 自身 ， 都 可 以 使 用 称 为 标 头 (header) 的 额 
外 字段 ， 包 含 更 多 信息 。 例 如 : 
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e User-Agent 标 头 字段 ， 为 请 求 提供 扩展 信息 ， 描 述 产生 这 个 请 求 的 应 用 程序 ; 
e Server 标 头 字段 ， 为 响应 提供 关于 源 服务 器 软件 的 扩展 信息 ， 
e Content-Type 标 头 字段 ， 定 义 请 求 或 响应 有 效 载 集 正 文中 ， 资 源 表示 使 用 的 媒体 类 型 。 











每 个 标 头 都 包括 一 个 名 字 和 一 个 值 ， 这 个 值 可 以 是 列表 。HTTP 规范 允许 一 个 销 息 的 多 个 
标 头 使 用 同样 的 名 字 。 但 是 ，HTTP 规范 也 规定 ， 多 个 标 头 使 用 同一 名 字 ， 效 果 等 同 于 定 
义 一 个 标 头 ， 甚 值 为 多 个 标 头 值 的 合集 。 已 广 册 的 HTTP 标 头 〈 参 见 http://www.iana.org/ 
assignments/message-headers/message-headers.xml) 由 IANA 维护 。 





如 图 10-1 所 示 ， 请 求 和 响应 消息 类 都 包含 一 个 Headers 属性 ， 指 同一 个 具有 类 型 的 标 头 容 
器 类 。 但 是 ， 内 容 标 头 〈 如 Content-Type) 不 属于 请 求 或 响应 的 标 头 集合 。 内 容 标 头 属于 
内 容 标 头 集合 ， 可 以 通过 HttpContent 的 Headers 属性 访问 。 














[Fact] 
public async void Message_and_content_headers_are_not_in_same_coll() 
{ 
using(var client = new HttpClient()) 
{ 
var response = await client 
.GetAsync("http://tools.ietf.org/html/rfc2616") ; 
var request = response.RequestMessage; 
Assert.Equal("tools.ietf.org",request.Headers.Host); 
Assert.NotNull(response.Headers.Server); 
Assert.Equal("text/html", 
response.Content.Headers.ContentType.MediaType) ; 


} 


ii TE ER, Server 标 头 在 response.Headers 容器 中 ， 而 Content Type $r k Æ response. 


oy an 


Content.Headers 容器 中 。 


HTTP 编程 模型 为 这 三 种 标 头 上 下 文 ， 各 自 定义 了 标 头 容器 类 : 








e HttpRequestHeaders 类 包含 请 求 标 头 ; 
e HttpResponseHeaders 类 包含 响应 标 头 ; 
。 HttpContentHeaders 类 包含 内 容 标 头 。 


这 三 个 类 都 有 一 组 属性 ， 以 强 类 型 方式 提供 标准 标 头 的 访问 。 例 如 : HttpRequestHeaders 
类 包含 一 个 Accept 属性 ， 其 类 型 为 MediaTypeWithQualityHeaderValue 集合 ， 集 合 中 每 个 
条 目 包含 如 下 内 容 : 





e MediaType 字符 串 属 性 ， 其 值 为 媒体 类 型 标识 符 (例如 : application/xml) ; 
e Quality 属性 (如 6.9) ; 
e CharSet 字符 串 属 性 ， 


。 Parameters 集合 属性 ; 
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下 一 段 代 码 展示 了 Accpet 标 头 的 使 用 。 因 为 类 模型 提供 了 对 所 有 组 成 部 分 (如 质量 参数 和 
字符 集 ) 的 访问 ， 使 用 标 头 非常 容易 。 


[Fact] 
public void Classes_expose_headers_in_a_strongly_typed_way() 
{ 
var request = new HttpRequestMessage(); 
request.Headers.Add( 
"Accept", 
"text/html, application/xhtml+xml, application/xml;q=0.9,*/*;q=0.8"); 


HttpHeaderValueCollection<MediaTypeWithQualityHeaderValue> accept = 
request.Headers.Accept; 
Assert.Equal(4,accept.Count) ; 


MediaTypeWithQualityHeaderValue third = accept.Skip(2).First(); 
Assert.Equal("application/xml", third.MediaType); 
Assert.Equal(0.9, third.Quality); 

Assert.Null(third.CharSet); 
Assert.Equal(1,third.Parameters.Count); 
Assert.Equal("q",third.Parameters.First().Name) ; 
Assert.Equal("0.9", third.Parameters.First().Value); 





} 
这 一 功能 极 大 地 简化 了 标 头 的 生成 和 使 用 ， 将 有 时 略 显 烦 琐 的 HTTP 语法 规则 进行 了 抽 
象 。 这 些 属 性 也 可 以 用 于 轻松 构建 标 头 的 值 ; 

[Fact] 

public void Properties_simplify_header_construction() 

{ 


var response = new HttpResponseMessage(); 
response.Headers.Date = 

new DateTimeOffset(2013,1,1,0,0,0, TimeSpan.FromHours(0)); 
response.Headers.CacheControl = new CacheControlHeaderValue 


{ 
MaxAge = TimeSpan.FromMinutes(1), 
Private = true 
}; 
var dateValue = response.Headers.First(h => h.Key == "Date") 


.Value.First(); 
Assert.Equal("Tue, 01 Jan 2013 00:00:00 GMT", dateValue); 


var cacheControlValue = response.Headers 
.First(h => h.Key == "Cache-Control").Value.First(); 
Assert.Equal('"max-age=60, private", cacheControlValue) ; 


} 











请 注意 ，CacheControlHeaderValue 类 为 每 个 HTTP 缓存 指令 (如 MaxAge 和 Private) 提供 
一 个 属性 。Date 标 头 是 用 一 个 DateTimeOffset 值 创建 的 ， 而 不 是 使 用 字符 串 ， 简 化 了 构建 
格式 正确 的 标 头 值 的 过 程 。 








有 些 标 头 的 值 是 纯 量 的 (如 Date)， 可 以 直接 赋值 ， 其 他 的 标 头 是 集合 值 ， 用 
HttpHeaderValueCollection<T> 泛 型 类 表示 ， 可 以 增加 和 删除 集合 中 的 值 : 


request.Headers.Date = DateTimeOffset.UtcNow; 
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("text/html",1.0)); 





图 10-2 展示 了 三 个 标 头 容器 类 ， 对 应 三 种 标 头 上 下 文 。 这 些 类 设 有 公共 的 构造 国 数 ， 不 能 
简单 地 单独 创建 ， 而 是 在 消息 或 内 容 实例 创建 时 一 同 创建 。 
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图 10-2: 三 个 标 头 容器 类 
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这 三 个 类 提供 的 属性 只 限于 由 HTTP RPC 定义 的 标 头 。 例 如 :， HttpRequestHeader 类 包含 
的 属性 ， 只 对 应 于 HTTP 请 求 可 以 使 用 的 标 头 。 而 且 ，HttpRequestHeader 类 不 提供 添加 非 


标准 标 头 的 方法 。 但 是 ， 这 三 个 类 都 派生 自 HttpHeaders 抽象 类 (如 
抽象 类 提供 








一 组 方法 ， 可 以 对 标 头 进行 较 低 层次 的 访问 。 








pa 





10-3 所 示 )， 








这 个 
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10-3; 基 类 HttpReaders 提供 对 标 头 集合 的 无 类 型 访问 
首先 ，HttpReaders 类 实现 了 如 下 接口 : 


IEnumerable<KeyValuePair<string,IEnumerable<string>>> 


使 用 这 个 接口 ， PAAA em AN FA, EI ak ee — EE , 4 


头 值 是 一 


个 字符 串 序 列 。 


HttpHeaders es 可 以 添加 和 删除 标 头 。 


Add 方法 可 以 向 容器 


UE. Add 方法 还 会 验证 标 头 是 否 可 以 有 多 个 值 。 


[Fact] 
public void Add_validates_value_domain_for_std_headers() 
{ 
var request = new HttpRequestMessage(); 
Assert. Throws<FormatException>(() => 
request.Headers.Add("Date", "invalid-date")); 
request.Headers.Add("Strict-Transport-Security", 





个 接口 保留 了 标 头 的 顺序 ， 支 持 了 标 头 值 作为 列表 的 情 ; 





"invalid ;; value"); 


添加 标 头 。 如 果 要 添加 的 标 头 有 标准 名 ， 在 添加 之 前 标 头 值 会 进行 验 





} 

Malas TryAddWithoutValidation 方法 不 执行 标 头 值 检验 。 但 是 ， 如 果 值 是 无 效 的 ， 就 
通过 有 类 型 的 属性 进行 访问 。 
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[Fact] 
public async void 


TryAddWithoutValidation_doesnt_validates_the_value_but_preserves_it() 


{ 


var request = new HttpRequestMessage(); 


Assert. True(request.Headers 


.TryAddWithoutValidation("Date", "invalid-date")); 
Assert.Equal(null, request.Headers.Date); 


Assert.Equal("invalid-date", request.Headers.GetValues("Date").First()); 


var content = new HttpMessageContent(request); 
var s = await content.ReadAsStringAsync(); 
Assert.True(s.Contains("Date: invalid-date")); 


} 








了 解 了 消息 和 内 容 如 何 使 用 标 头 扩展 信息 ， 下 


10.3 消息 内 容 
在 新 的 HTTP 编程 模型 中 ，HTTP 消息 的 正文 由 抽象 基 类 Httpcontent 表示 (参见 图 10-4), 








市 我 们 将 关注 内 容 自 身 。 


HttpRequestMessage 和 HttpResponseMessage 都 包含 一 个 HttpContent 类 型 的 Content 属性 


(参见 图 10-1), 
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10-4: HttpContent 基 类 以 及 相关 类 层次 
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在 这 一 节 中 ， 我 们 将 了 解 : 


。 如 何 通 过 HttpContent 的 方法 使 用 消息 内 容 ，; 
。 如 何 通 过 现 有 的 HttpContent 派生 有 具体 的 类 ， 或 者 创建 一 个 新 类 ， 生 成 消息 内 容 。 


10.31 ”使 用 消息 内 容 
在 创建 消息 内 容 时 ， 我 们 可 以 选择 一 个 可 用 的 由 HttpContent 派生 的 具体 类 。 然 而 ， 在 使 
用 消息 内 容 时 ， 我 们 只 能 使 用 HttpContent 的 方法 或 者 扩展 方法 。 





除了 前 一 节 中 介绍 的 Headers 属性 ，HttpContent 还 包含 如 下 非 虚拟 的 公共 方法 : 


e Task CopyToAsync(Stream, TransportContext) 
e Task<Stream> ReadAsStreamAsync() 

。 Task<string> ReadAsStringAsync() 

e Task<byte[]> ReadAsByteArrayAsync() 


一 方法 可 以 用 于 以 推送 (push) 方式 访问 原始 的 消息 内 容 。 我 们 将 一 个 流传 递 给 


CopyToAsync 方法 ， 然 后 CopyToAsync 把 消息 内 容 写 入 (推送 ) 到 这 个 流 中 。 返 回 的 Task 
可 以 用 于 与 复制 终止 进行 同步 : 


[Fact] 
public async Task HttpContent_can_be_consumed_in_push_style() 
{ 
using (var client = new HttpClient()) 
{ 
var response = 
await client.GetAsync("http://www.ietf.org/rfc/rfc2616.txt", 
HttpCompLetionOption.ResponseHeadersRead 
); 
response. EnsureSuccessStatusCode() ; 
var ms = new MemoryStream(); 
await response.Content.CopyToAsync(ms) ; 
Assert.True(ms.Length > 0); 
} 


} 





前 面 这 个 示例 使 用 了 HttpCompLletionOption.ResponseHeadersRead 选项 ， 使 TA 方法 
在 响应 头 读 取 之 后 立即 终止 ， 响 应 内 容 可 以 使 用 CopyToAsync 方法 访问 ， 无 需 进行 缓冲 。 








二 








你 也 可 以 使 用 ReadAsStreamAsync 方法 ， 以 拉 取 (pull) 方式 访问 原始 的 消息 内 容 。 这 个 方 
法 异步 返回 一 个 流 ， 可 以 从 中 获取 内 容 。 


[Fact] 
public async Task HttpContent_can_be_consumed_in_pull_style() 


{ 


using (var client = new HttpClient()) 





var response = await 
client.GetAsync("http://www.ietf.org/rfc/rfc2616.txt"); 

response. EnsureSuccessStatusCode( ); 

var stream = await response.Content.ReadAsStreamAsync(); 

var buffer = new byte[2*1024]; 

var len = await stream.ReadAsync(buffer, 0, buffer.Length); 

var s = Encoding.ASCII.GetString(buffer, 0, len); 

Assert. True(s.Contains("Hypertext Transfer Protocol -- HTTP/1.1")); 


} 
最 后 两 种 方法 异步 地 提供 消息 内 容 的 


缓冲 副本 。ReadAsByteArrayAsync 返回 原始 的 字 节 内 容 ， 而 ReadAsStringAsync 将 内 容 解码 
为 字符 串 返 回 。 








ReadAsStringAsync 和 ReadAsByteArrayAsync 











[Fact] 
public async Task HttpContent_can_be_consumed_as_a_string() 
{ 
using (var client = new HttpClient()) 
{ 
var response = await 
client.GetAsync("http://www.ietf.org/rfc/rfc2616.txt"); 
response. EnsureSuccessStatusCode( ); 
var s = await response.Content.ReadAsStringAsync(); 
Assert. True(s.Contains("Hypertext Transfer Protocol -- HTTP/1.1")); 
} 


} 


除了 HttpContent EPMA, ASAE HttpContentExtensions 也 定义 了 扩展 方法 。 所 有 扩 
展 方法 都 是 以 下 方法 的 变种 : 
public static Task<T> ReadAsAsync<T>( 
this HttpContent content, 


IEnumerable<MediaTypeFormatter> formatters, 
IFormatterLogger formatterLogger ) 


这 个 方法 接受 一 列 媒体 类 型 格式 化 程序 ， 尝 试 使 用 其 中 一 个 格式 化 程序 ， 将 消息 内 容 读 取 
为 类 型 T 的 实例 : 


class GitHubUser 


{ 
public string login { get; set; } 
public int id { get; set; } 
public string url { get; set; } 
public string type { get; set; } 

} 

[Fact] 


public async Task HttpContent_can_be_consumed_using_formatters() 


{ 
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using (var client = new HttpClient()) 
{ 
var response = await 
client.GetAsync("https://api.github.com/users/webapibook") ; 
response. EnsureSuccessStatusCode() ; 
var user = await response.Content 
.ReadAsAsync<GitHubUser>(new MediaTypeFormatter[ ] 


{ 
new JsonMediaTypeFormatter() 
D; 
Assert.Equal("webapibook", user.login); 
Assert.Equal("Organization", user.type); 


} 


媒体 类 型 格式 化 程序 (第 13 章 将 详细 介绍 ) 是 抽象 类 MediaTypeFormatter 的 派生 类 ， 在 
对 象 和 字 节 流 表示 (由 因特网 媒体 类 型 定义 ) 之 间 进 行 双向 转换 。 


ReadAsAsync 方法 也 有 一 个 过 载 方法 不 需要 媒体 类 型 格式 化 程序 序列 参数 ， 而 是 使 用 一 组 
默认 的 格式 化 程序 。 目 前 ， 这 组 默认 的 格式 化 程序 是 : JsonMediaTypeFormatter、XmLMe 
diaTypeFormatter 和 FormUrlEncodedMediaTypeFormatter , 





10.3.2 创建 消息 内 容 

在 创建 有 效 载 答 不 为 空 的 消息 时 ， 我 们 按照 内 容 的 类 型 选择 HttpContent A 
例 ， 赋 给 Content 类 型 属性 。 图 10-4 展示 了 一 些 可 用 的 类 。 例 如 ， 如 果 消 息 内 容 是 纯 
本 ， 那 么 我 们 可 以 用 StringContent 类 来 表示 。 























[Fact] 
public void StringContent_can_be_used_to_represent_plain_text() 
{ 

var response = new HttpResponseMessage() 


{ 


}; 
Assert.Equal("text/plain", response.Content.Headers.ContentType.MediaType) ; 


Content = new StringContent("this is a plain text representation") 


} 
在 默认 情况 下 ，Content-Type 标 头 设置 为 text/plain， 但 这 个 值 是 可 以 修改 的 。 


FormUrLEncodedContent 类 用 于 生成 名 字 / 值 对 ， 按 照 a a 规则 
(HTML 表单 也 使 用 同样 的 编码 规则 ) 进行 编码 。 这 些 名 字 / 值 对 通过 FornurtEncodedcontent 
构造 函数 的 TEnumerable<KeyValuePair<string,string>> 参数 定义 。 





[Fact] 
public async Task FormUrlEncodedContent_can_represent_name_value_pairs() 


{ 


var request = new HttpRequestMessage 





Content = new FormUrLEncodedContent( 
new Dictionary<string, string>() 
{ 
{"namei", "valuei"}, 
"name2", "value2"} 
}) 
J}; 
Assert.Equal("application/x-www-form-urlencoded", 
request.Content.Headers.ContentType.MediaType) ; 
var stringContent = await request.Content.ReadAsStringAsync(); 
Assert. Equal("name1=value1&name2=value2", stringContent) ; 


} 


编程 模型 还 提供 了 另外 三 个 类 ， 在 已 经 得 到 字 节 序列 的 内 容 时 使 用 。 如 果 内 容 包含 在 一 个 
字 节 数组 中 ， 我 们 可 以 使 用 ByteArrayContent 类 。 




















[Fact] 
public async Task ByteArrayContent_can_represent_byte_sequences() 


{ 
var alreadyExistantArray = new byte[] { 0x48, 0x65, Ox6c, Ox6c, Ox6f}; 


var content = new ByteArrayContent(alreadyExistantArray); 
content.Headers.ContentType = new MediaTypeHeaderValue( "text/plain" ) 
{ CharSet = "utf-8" }; 
var readText = await content.ReadAsStringAsync(); 
Assert.Equal("Hello", readText); 
} 


StreamContent 和 PushStreamContent 类 都 用 于 流 的 处 理 : 如 果 内 容 已 经 在 流 中 (例如 ， 
从 文件 中 读 取 得 到 )， 可 以 使 用 StreamContent; 而 当 内 容 由 流 输出 产生 时 ， 应 当 使 用 


PushStreamContent , 








StreamContent 实例 创建 时 ， 构 造 函 数 中 传 入 一 个 流 。 之 后 ， 在 序列 化 HTTP 消息 时 ， 
HTTP 模型 运行 时 会 从 这 个 流 中 拉 取 字 贡 序列， 添加 到 序列 化 的 消息 正文 中 。 


[Fact] 

public async Task StreamContent_can_be_used_when_content_is_in_a_stream() 

{ 
const string thisFileName = @"..\..\HttpContentFacts.cs"; 
var stream = new FileStream(thisFileName, FileMode.Open, FileAccess.Read); 
using (var content = new StreamContent(stream) ) 


{ 
content.Headers.ContentType = new MediaTypeHeaderValue("text/plain"); 
// 断言 
var text = await content.ReadAsStringAsync(); 
Assert. True(text.Contains("this string")); 
} 


Assert. Throws<ObjectDisposedException>(() => stream.Read(new byte[1], 0, 1)); 
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当 包含 这 个 流 的 StreamContent 实例 释放 时 (例如 ， 由 Web API 运行 时 释放 )， 这 个 流 会 
随 之 释放 。 


然而 ， 在 有 的 情况 下 ， 内 容 并 没有 准备 好 ， 而 是 由 一 个 进程 产生 内 容 ， 这 个 进程 需要 使 用 
一 个 流 ， 将 内 容 写 入 其 中 。 一 个 典型 的 例子 是 使 用 xmLwriter 进行 XML 序列 化 ， 需 要 向 
一 个 输出 流 中 写 入 序列 化 的 字 市 。 一 个 解决 办 法 是 使 用 一 个 作为 中 介 的 MemoryStream, fh] 
其 中 写 入 内 容 ， 然 后 将 这 个 内 存 流传 递 给 一 个 StreamContent 实例 。 但 是 ， 这 种 办 法 会 产 
生 一 个 中 间 的 副本 ， 不 太 适 合流 媒体 的 使 用 场景 。 




















一 个 更 好 的 办 法 是 使 用 PushStreamContent 类 。PushStreamContent 接受 一 个 Action<Stream, 
.> 操作， 以 推送 方式 (push-style) 运行 : 当 运 行 时 将 流 准备 好 时 (例如 ， 底 层 的 ASP. 
NET 响应 内 容 流 )， 就 会 调用 PushStreamContent 的 流 操 作 ， 该 操作 负责 将 内 容 写 到 最 终 的 
流 中 ,不 需要 进行 任何 中 间 的 缓冲 。 





[Fact] 
public async Task 
PushStreamContent_can_be_used_when_content_is_provided_by_a_stream_writer() 


{ 
var xml = new XElement("root", 
new XElement("childi", "text"), 
new XElement("child2", "text") 
J; 
var content = new PushStreamContent((stream, cont, ctx) => 
{ 
using (var writer = XmlWriter.Create(strean, 
new XmlWriterSettings { CloseOutput = true })) 
{ 
xml.WriteTo(writer) ; 
} 
}) 
content.Headers.ContentType = 
new MediaTypeWithQualityHeaderValue("application/xmLl"); 
// 断言 
var text = await content.ReadAsStringAsync(); 
Assert. True(text.Contains("<child1")); 
} 





要 注意 的 重要 一 点 是 ， 这 个 操作 不 必 同 步 地 写 入 全 部 内 容 。 实 际 上 ， 只 有 当 流 关闭 时 ， 运 
行 时 才 认 为 内 容 全 部 写 和 完毕， 而 不 是 在 操作 返回 时 完成 。 这 意味 着 ， 可 以 在 操作 返回 之 
后 ， 由 操作 安排 的 代码 将 内 容 写 入 流 (Bilan: 异步 任务 或 者 定时 器 回调 )。 唯 一 的 要 求 是 ， 
必须 调用 流 的 Close 方法 ， 以 通知 运行 时 内 容 已 经 完全 写 入 。 遗 憾 的 是 ， 如 果 一 个 错误 在 
操作 返回 之 后 发 生 ， 那 么 这 个 错误 的 发 生 就 没有 办 法 通知 给 运行 时 。 唯 一 可 能 的 行为 是 
关闭 流 ， 但 是 关闭 流 无 法 区 分 写 入 成 功 还 是 失败 。 为 了 解决 这 个 问题 ， 新 版 本 的 System. 
Net.Http.Formatting.dll 程序 集 提 供 PushStreamContent 的 一 个 新 的 过 载 方法 ， 接 受 一 个 
Func<Stream，HttpContent，TransportContext，Task>。 使 用 这 个 新 的 过 载 方 法 ， 异 步 代 码 









































可 以 返回 一 个 Task， 用 于 通知 运行 时 异常 的 发 生 。 请 注意 ， 在 下 面 一 个 示例 中 ，Lambda 
表示 式 使 用 了 前 级 async， 表 明 将 返回 一 个 Task, 














[Fact] 
public async Task PushStreamContent_can_be_used_asynchronously() 


{ 


} 


const string text = "will wait for 2 seconds without blocking"; 
var content = new PushStreamContent(async (stream, cont, ctx) => 
{ 
await Task.Delay(2000); 
var bytes = Encoding.UTF8.GetBytes(text) ; 
stream.Write(bytes, 0, bytes.Length); 
stream.Close(); 
}); 
content.Headers.ContentType = 
new MediaTypeWithQualityHeaderVaLlue("text/plain"); 


// 断言 

var sw = new Stopwatch(); 

sw.Start(); 

var receivedText = await content.ReadAsStringAsync(); 
sw.Stop(); 

Assert.Equal(text, receivedText); 

Assert. True(sw.ELapsedMilliseconds > 1500); 


前 面 介绍 的 代表 消息 内 容 的 类 都 要 求 内 容 是 字 市 序列 。 但 是 ， 新 的 HTTP 编程 模型 也 包含 
ObjectContent 和 0bjectContent<T> 类 ， 可 以 直接 从 对 象 定义 HTTP 消息 内 容 。 在 其 内 部 ， 
这 些 类 使 用 媒体 类 型 格式 化 程序 将 对 象 转换 为 字 节 序列 。 





ObjectConent 构造 函数 中 进行 定义 。 


[Fact] 


public async Task ObjectContent_uses_mediatypeformatter_to_produce_the_content() 


{ 


var representation = new 


{ 

field1 = "a string", 
field2 = 42, 

field3 = true 

}; 


var content = new ObjectContent( 
representation.GetType(), 
representation, 
new JsonMediaTypeFormatter()); 


// 断言 


Assert.Equal("application/json",content.Headers.ContentType.MediaType); 


var text = await content.ReadAsStringAsync(); 




















在 接 下 来 的 示例 中 ， 我 们 为 一 个 带 有 三 个 域 的 匿名 类 生成 一 个 JSON 表示 。 请 注意 ， 要 使 


用 的 媒体 类 型 格式 化 程序 一 一 在 这 个 例子 中 为 JsonMediaTypeFormatter 一 一 必须 明确 地 在 
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var obj = JObject.Parse(text); 
Assert.Equal("a string", obj["fieldi"]); 
Assert.Equal(42, obj["field2"]); 
Assert.Equal(true, obj["field3"]); 


} 


ObjectConent 既 需要 和 输入 对 象 的 值 ， 也 需要 对 象 类 型 。 甚 泛 型 版 本 ，0bjectContent<T>， 
只 是 对 ObjectContent 进行 了 简化 ， 将 输入 类 型 定义 为 泛 型 参数 。 


新 编程 模型 的 HttpRequestMessageExtensions 类 提供 一 组 扩展 方法 ， 可 以 简化 从 请 求 创 建 
响应 的 工作 。 例 如 ， 你 可 以 创建 一 个 响应 消息 ， 自 动 链接 到 对 应 的 请 求 消息 。 


[Fact] 
public void HttpRequestMessage_has_a_CreateResponse_extension_method() 


{ 


var request = 
new HttpRequestMessage(HttpMethod.Get, 
new Uri("http://www.example.net")); 
var response = request.CreateResponse(HttpStatusCode. OK) ; 
Assert.Equal(request, response.RequestMessage) ; 


} 


你 可 以 使 用 CreateResponse 的 过 载 方 法 ， 指 定 媒体 类 型 格式 化 程序 ， 从 对 象 创 建 一 个 表 
示 ， 完 成 与 0bjectContent 类 似 的 功能 : 


public void CreateResponse_can_receive_a_formatter() 


{ 
var request = 
new HttpRequestMessage(HttpMethod.Get, 
new Uri("http://www.example.net")); 
var response = request.CreateResponse( 
HttpStatusCode.0K, 
new { String = "hello", AnInt = 42 }, 
new JsonMediaTypeFormatter()); 
Assert.Equal("application/json", 
response. Content .Headers.ContentType.MediaType) ; 
} 


在 服务 器 驱动 的 内 容 协 商场 景 中 ， 需 要 使 用 请 求 信息 一 一 即 请 求 的 Accept 标 头 一 一 决定 最 
合适 的 媒体 类 型 ， 此 时 CreateResponse 方法 特别 适合 。 





[Fact] 
public void CreateResponse_performs_content_negotiation() 
{ 
var request = 
new HttpRequestMessage(HttpMethod.Get, 
new Uri("http://www.example.net")); 
request.Headers.Accept.Add( 
new MediaTypeWithQualityHeaderValue("application/xml", 0.9)); 





request.Headers.Accept.Add( 

new MediaTypeWithQualityHeaderValue("application/json", 1.0)); 
var response = request.CreateResponse( 

HttpStatusCode.OK, 

"resource representation", 

new HttpConfiguration()); 


Assert.Equal("application/json", 
response.Content.Headers.ContentType.MediaType) ; 


} 
请 注意 ， 这 里 使 用 的 CreateResponse 过 载 使 用 一 个 带 有 已 配置 格式 化 程序 的 Http 


Configuration。 





最 后 ， 你 也 可 以 选择 创建 定制 的 HttpContent 派生 类 ， 生 成 消息 内 容 。 但 是 ， 在 我 们 介绍 
这 项 技术 之 前 ， 需 要 先 理解 HTTP 消息 内 容 的 长 度 是 如 何 计算 的 。 


1. 内 容 长 度 和 流 
在 HTTP F, 定义 有 效 载 符 的 正文 长 度 主 要 有 三 种 方法 : 
。 添加 一 个 Content-Length 标 头 字段 ， 显 式 地 指定 消息 长 度 ， 


。 使 用 分 块 传输 编码 (chunked transfer encoding)， 隐 式 地 指定 消息 长 度 ， 
。 在 所 有 内 容 传 输 完毕 后 关闭 链接 (只 适用 于 响应 内 容 )， 隐 式 地 指定 消息 长 度 。 














最 后 一 种 方法 主要 是 为 了 与 HITP 1.0 兼 容 ， 不 应 该 使 用 ， 因 为 连接 的 异常 中 断 会 导致 无 
法 检测 的 内 容 损坏 。 


使 用 分 块 传输 编码 ， 消 息 正文 分 为 一 系列 块 (chunk)， 每 块 带 有 自己 的 大 小 定义 。 对 于 流 
媒体 内 容 ， 其 长度 信息 无 法 预知 ， 如 有 果 使 用 分 块 传输 编码 ， 不 需要 缓冲 就 可 以 进行 传输 。 








第 一 种 方法 比较 简单 ， 但 是 需要 预先 知道 内 容 的 长 度 。 为 此 ，HttpContent 类 定义 了 如 下 
的 抽象 方法 : 


protected internal abstract bool TryComputeLength(out long length) 





每 个 具体 的 内 容 类 ， 都 必须 按照 其 内 容 的 表示 方式 ， 实 现 这 个 方法 。 例 如 : ByteArraryContent 
类 实现 的 TryComputeLength 方 法 总 是 返回 true， 提 供 底 层 的 数组 长 度 。 而 
PushStreamContent 类 的 实现 返回 false， 因 为 其 内 容 是 由 注册 的 操作 动态 推送 的 。 请 注 
意 ，PushStreamContent 类 无 法 知道 这 个 操作 将 会 推送 多 少 个 字 节 。 最 后 ，StreamContent 
类 的 实现 将 这 个 查询 委托 给 其 构造 函数 中 定义 的 底层 Stream, 如 果 这 个 流 是 可 定位 的 
(seekable), [SZ TryComputeLength 方法 就 使 用 Stream. Length 计算 内 容 长 度 ; Aull, Try 
ComputeLength 方法 会 返回 false。 
































TryComputeLength 方法 与 Long? HttpContentHeaders.ContentLength 属性 之 间 的 关系 也 很 紧 
密 : 如 果 这 个 属性 值 没有 明确 赋值 ， 那 么 就 会 查询 TryComputeLength 方法 。 也 就 是 说 ， 我 
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们 不 需要 明确 指定 Content-Length 标 头 的 值 ， 除 非 需要 从 外 部 方法 获得 内 容 长 度 信息 。 还 
要 注意 ，HttpContentHeaders.ContentLength 的 类 型 是 Long? ， 人 允许 使 用 空 值 。 














在 第 11 章 中 ， 我 们 将 会 介绍 托管 层 如何 使 用 消息 的 内 容 长 度 ， 决 定 处 理 响应 消息 内 容 的 
最 佳 方式 〈 即 决定 是 否 应 该 使 用 缓冲 ) 。 





2. 定制 内 容 类 

现在 我 们 已 经 知道 了 消息 内 容 的 长 度 是 如 何 定义 的 ， 以 及 什么 影响 流 ， 接 下 来 要 介 
绍 定制 内 容 类 的 创建 。 接 下 来 的 一 段 代码 定义 了 一 个 FileContent 类 ， 这 个 类 派生 自 
HttpContent， 是 一 个 代表 文件 内 容 的 定制 类 。 


public class FileContent : HttpContent 


{ 
private readonly Stream _stream; 
public FileContent(string path, 
string mediaType = "application/octet-stream") 
{ 
_stream = new FileStream(path, FileMode.Open, FileAccess.Read); 
base.Headers.ContentType = new MediaTypeHeaderValue(mediaType) ; 
} 
protected override Task 
SerializeToStreamAsync(Stream stream, TransportContext context) 
{ 
return _stream.CopyToAsync(stream) ; 
} 
protected override bool TryComputeLength(out long Length) 
{ 
if (!_stream.CanSeek) 
{ 
length = 0; 
return false; 
} 
else 
{ 
length = _stream.Length; return true; 
} 
} 
protected override void Dispose(bool disposing) 
{ 
_stream.Dispose(); 
} 
} 


创建 定制 的 HttpContent 类 ， 需 要 定义 下 面 两 个 抽象 方法 : 


protected internal abstract bool TryComputeLength(out long length); 
protected abstract Task SerializeToStreamAsync( 
Stream stream, TransportContext context); 





上 一 节 曾 经 介绍 过 ， 第 一 个 方法 一 一 TryComputeLength 一 一 用 于 尝试 获得 内 容 长 度 。 在 








FileContent 的 实现 中 ， 这 个 方法 使 用 Stream.CanSeek 属性 ， 查 询 是 否 能 够 计算 文件 流 的 
长 度 ， 如 果 文 件 流 长 度 可 以 计算 ， 就 使 用 Stream.Length 属性 ， 返 回 内 容 长 度 。 




















第 二 个 方法 ，SerializeToStreamAsync， 人 负责 将 内 容 写 到 传 入 的 Stream。 这 个 方法 可 以 
异步 操作 ， 在 写 和 完成 前 返回 一 个 Task。 当 写 入 过 程 结 束 时 ， 这 个 返回 的 Task 应 该 得 
到 通知 。 当 消息 内 容 由 另 一 个 异步 过 程 提供 时 【〈 例 如 : 从 文件 系统 或 外 部 系统 读 入 )， 
SerializeToStreamAsync 方法 的 这 种 异步 能 力 就 非常 有 用 。 例 如 ，FiLeCcontent 的 实现 使 用 
了 .NET4.5 中 引入 的 CopyToAsync 方法 ， 开 始 异步 复制 操作 ， 并 返回 代表 这 一 操作 的 Task, 

















除了 直接 继承 HttpContent 类 ， 你 也 可 以 采取 另 一 种 方法 使 用 StreamContent 和 
PushStreamContent 类 。 你 可 以 继承 StreamContent 或 PushStreamContent 类 ， 或 者 通过 工 
厂 方法 使 用 这 两 个 类 。 下 面 的 代码 创建 了 PushstreamContent 的 一 个 派生 类 ， 不 需要 使 用 
任何 缓 串 ， 就 可 以 构建 基于 XML 的 内 容 。 

















public class XmlContent : PushStreamContent 


{ 
public XmlContent(XElement xe) 
: base(PushStream(xe), "application/xmL") 
{ 
} 
private static Action<Stream,HttpContent, TransportContext> 
PushStream(XElement xe) 
{ 
return (stream, content, ctx) => 
{ 
using (var writer = XmlWriter.Create(stream, 
new XmlWriterSettings(){CloseOutput = true})) 
{ 
xe.WriteTo(writer); 
} 
}; 
} 
} 


因为 PushStreamContent 的 构造 函数 需要 一 个 Action<Stream,HttpContent, Transport 
Context>， 前 面 的 示例 中 使 用 了 一 个 私有 的 静态 方法 ， 从 提供 的 XElement 创建 了 这 个 操 
作 。 还 需要 注意 的 是 ， 代 码 中 使 用 了 pe 参数 ， 以 关闭 提供 的 流 。 因 为 操 
作假 定 是 异步 的 ， 关 闭 流 就 标识 着 这 一 过 程 的 终结 。 


我 们 可 以 对 XELement 使 用 一 个 扩展 方法 ， 实 现 同样 的 功能 




















public static class XElementContentExtensions 


{ 


public static HttpContent ToHttpContent(this XElement xe) 


{ 


return new PushStreamContent((stream, content, ctx) => 


{ 
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using (var writer = XmlWriter.Create(stream, 
new XmlWriterSettings(){CloseOutput = true})) 


{ 


xe.WriteTo(writer ) 


},"application/xml"); 


10.4 “小 结 


本 章 ， 我 们 关 广 的 是 新 的 HTTP 编程 模型 ， 


2 


这 一 编程 模型 在 .NET 框架 的 4.5 版 本 中 引入 ， 





是 Web API 以 及 新 HttpClient 类 的 核心 。 正 如 我 们 介绍 的 ， 这 个 新 的 编程 模型 提供 了 实 








现 可 用 性 和 可 测试 性 的 更 好 方式 ， 用 于 处 理 








HTTP 的 核心 概念 消息 、 标 头 和 内 容 。 之 


后 的 章节 将 在 此 基础 之 上 ， 帮 助 你 更 深入 理解 Web API 的 内 部 工作 方式 。 也 就 是 说 ， 第 
11 章 将 介绍 HTTP 编程 模型 与 一 个 底层 HTTP 栈 (例如 ASP.NET 提供 的 HTTP 栈 ) 之 间 








的 接口 。 





226 | 第 10 章 


第 11 章 
te 





Web API 遇 见 了 楼 下 的 邻居 。 


第 4 章 将 ASP.NET Web API 处 理 架 构 分 为 三 层 : 托管 、 消 息 处 理 程序 管道 和 控制 器 处 理 。 
本 章 要 详细 介绍 其 中 的 第 一 层 : 托管 。 








托管 层 实际 上 是 一 个 宿主 适 配 层 (host adaptation layer)， 这 一 层 作 为 一 个 桥梁 ， 连 接 Web 
API 处 理 架 构 和 所 支持 的 外 部 托管 基础 结构 。 实 际 上 ，Web API 自身 并 没有 托管 机 制 。 恰 
恰 相反 ，Web API 的 目标 是 独立 于 宿主 ， 可 以 在 多 种 托管 场景 下 使 用 。 


概括 起 来 ， 宿 主 适 配 层 负责 执行 如 下 任务 : 





。 创建 和 初始 化 消息 处 理 器 管道 ， 将 其 封装 在 HttpServer 实例 中 ， 

。 从 底层 的 托管 基础 结构 接收 HTTP 请 求 。 这 一 任务 通常 通过 注册 一 个 回调 函数 实现 ，; 

。 将 HTTP 请求 从 本 地 表示 (如 ASP.NET 的 HttpRequest) 转 换 成 HttpRequestMessage 实例 ， 
。 将 这 些 HttpRequestMessage 实例 推送 到 消息 处 理 器 管道 ， 以 此 开始 Web API 请 求 处 理 ， 


=<, 








。 当 一 个 响应 生成 并 返回 时 ， 宿 主 适 配 层 将 返回 的 HttpResponsemessage 实例 转换 成 底层 
H 








础 结构 的 本 地 响应 表示 (如 ASP.NET 的 HttpResponse) , 传递 给 底层 的 托管 基础 结构 。 


ASP.NET Web API 1.0 支持 两 种 托管 适 配 层 : Web 托管 和 自 托管 。 使 用 Web 托管 适 配 层 ， 
我 们 可 以 在 经 典 的 HS 支持 的 ASP.NET 托管 基础 结构 上 使 用 Web API。 使 用 自 托管 适 配 
层 ， 我 们 可 以 在 任何 Windows 进程 (E: 控制 台 应 用 程序 和 Windows 服务 ) 上 使 用 Web 
API。 这 两 种 托管 适 配 层 可 以 通过 独立 的 NuGet 软件 包 获 得 : Microsoft.AspNet.WebApi. 
WebHost 和 Microsoft.AspNet.WebApi.SelfHost, ASP.NET Web API 2.0 引入 了 OWIN 托管 
适 配 层 ， 可 以 通过 Microsoft.AspNet.WebApi.Owin 软件 包 下 载 。 使 用 这 个 新 的 托管 适 配 层 ， 








227 


我 们 可 以 在 任何 OWIN 兼容 的 宿主 上 运行 Web API, 


本 章 的 目的 是 为 你 提供 必要 的 知识 ， 在 这 些 托管 场景 中 充分 使 用 Web API。 为 了 实现 这 
一 目标 ， 我 们 将 更 为 深入 地 介绍 这 些 托管 适 配 层 ， 关 注 其 内 部 行为 。 我 们 还 会 以 Azure 
Service Bus 适 配 层 为 例 ， 通 过 Service Bus 中 继 ， 将 私有 托管 的 Web API 应 用 安全 提供 给 
公共 Web， 详 细 介 绍 如 何 支持 新 的 托管 场景 。 
































最 后 ， 我 们 还 将 介绍 一 个 针对 测试 场景 ， 通 常 称 为 内 存 托管 〈in-memory hosting) 的 特殊 
托管 方式 。 这 种 托管 方式 直接 将 一 个 HttpCLient 实例 连接 到 一 个 Web API HttpServer 实 
例 ， 客 户 端 和 服务 器 可 以 进行 在 内 存 中 直接 进行 HTTP 通信 。 





掌握 了 这 些 内 部 的 实施 架构 ， 我 们 可 以 正确 地 进行 Web API 托管 的 配置 和 优化 (如 消息 缓 
冲 )。 如 果 你 想 编写 一 个 定制 的 宿主 或 者 扩展 现 有 的 宿主 ， 本 章 的 内 容 也 会 有 所 帮助 。 
Web API 的 托管 机 制 涉及 若干 外 部 技术 ， 例 如 : 经 典 的 ASP.NET 管道 、WCF 信道 栈 层 
(channel stack layer) 或 OWIN 规范 。 为 了 内 容 的 完整 性 ， 本 章 也 会 简要 介绍 这 些 外 部 技 
术 ， 尤 其 是 其 中 与 托管 相关 的 部 分 。 


11.1 Web 托 管 


所 谓 的 Web 托管 使 用 经 典 的 ASP.NET 管道 。 接 下 来 ， 我 们 将 首先 回顾 ASP.NET 管道 的 
相关 内 容 ， 然 后 简要 描述 Web API 和 ASP.NET MVC 使 用 的 ASP.NET 路 由 基础 结构 ， 最 
后 介绍 Web API 如 何 将 二 者 集成 在 一 起 。 


11.1.1 ASP.NET 基 础 结构 























如 图 11-1 Aras, ASP.NET 基础 结构 有 三 个 主要 元 素 : 应 用 程序 、 模 块 和 处 理 程 


|HttpAsyncHandler 
|HttpHandler 
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IHttpModule 
IHttpModule 
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1. 应 用 程序 
在 ASP.NET 中 ， 部 署 单元 是 应 用 程序 ， 表 示 为 HttpApplication 类 。 通 过 定义 一 个 定制 的 
global.asax 文件 ， 你 可 以 为 每 个 应 用 程序 创建 一 个 特殊 的 派生 类 。 














如 有 果 一 个 请 求 映 射 到 一 个 应 用 程序 ， 运 行 时 就 会 创建 或 者 选择 一 个 HttpApplication 实例 ， 
处 理 这 个 请 求 。 运 行 时 还 会 创建 一 个 上 下 文 ， 表示 HTTP 请 求 和 响应 : 




















public sealed class HttpContext : IServiceProvider 


{ 
public HttpRequest Request { get {...} } 
public HttpResponse Response { get {...} } 


} 


应 用 程序 接着 会 让 这 个 上 下 文 “ 流 经 ”一 组 管道 阶段 ， 这 些 阶段 由 HttpApplication 成 员 
事件 表示 。 例 如 : 请 求 开 始 处 理 时 会 触发 HttpApplication.BeginRequest 事件 。 


2. 模块 
一 个 应 用 程序 包含 一 组 注册 的 模块 类 ， 实 现 IHttpModule 接口 : 





























public interface IHttpModule 
{ 


void Dispose(); 
void Init(HttpApplication context); 


} 


一 个 新 的 应 用 程序 对 象 在 构建 时 ， 会 为 每 个 模块 类 创建 一 个 实例 ， 并 调用 这 些 实例 的 
IHttpModule.Init 方法 。 每 个 模块 利用 这 个 调用 ， 将 自己 附加 (attach) 在 想 要 处 理 的 管道 
事件 上 。 一 个 模块 可 以 附加 在 多 个 事件 上 ， 一 个 事件 可 以 有 多 个 模块 附加 其 上 。 


随后 这 些 模块 可 以 作为 过 滤 程 序 ， 在 HTTP 请 求 和 响应 流 经 事件 管道 时 对 其 进行 处 理 。 
些 模块 也 可 以 提前 乡 iAH, 立刻 产生 响应 。 












































3. 处 理 程 序 
在 触发 所 有 的 请 求 事件 之 后 ， 应 用 程序 选择 一 个 处 理 程序 
IHttpAsyncHandler 接口 )， 将 请 求 的 处 理工 作 委 托 给 这 个 处 理 程 








表示 为 IHttpHandler 或 





a 





public interface IHttpHandler 


{ 


void ProcessRequest(HttpContext context); 
bool IsReusable { get; } 


public interface IHttpAsyncHandler : IHttpHandler 


{ 
TAsyncResult BeginProcessRequest(HttpContext context, 
AsyncCallback cb, object extraData); 
void EndProcessRequest(IAsyncResult result); 
} 
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当 处 理 程 序 的 处 理 结束 时 ， 这 个 上 下 文 流 回应 用 程序 管道 ， 触 发 响应 事件 。 

















处 理 程序 是 应 用 程序 最 终 委 托 请 求 处 理 的 端点 (endpoint)， 构 成 了 基于 ASP.NET 基础 结 
构 的 多 个 框架 (如 Web Forms, ASP.NET MVC 或 Web API) 使 用 的 主要 集成 点 。 














例如 ， 在 ASP.NET Web Forms 框架 中 ，System.Neb.UI.Page 类 实现 了 IHttpHanlder 接口 。 
也 就 是 说 ， 类 与 一 个 .aspx 文件 结合 构成 了 一 个 处 理 程序 ， 如 果 请 求 URI 与 这 个 .aspx 文件 
路 径 匹 配 ， 应 用 程序 就 会 调用 这 个 处 理 程 序 。 


我 们 通过 将 请 求 URI 映射 到 应 用 程序 目录 中 的 一 个 文件 (例如 : 一 个 aspx XIE), RE 
使 用 ASP.NET 路 由 功能 ， 来 选择 处 理 程序 。ASP.NET Web Forms 使 用 前 一 种 技术 |, Ta 
ASP.NET MVC 使 用 后 一 种 。Web API 也 使 用 ASP.NET 路 由 功能 ， 接 下 来 将 进行 介绍 。 








11.1.2 ASP.NET 路 由 


在 ASP.NET 基础 结构 中 ， 配 置 路 由 的 通常 方法 是 将 路 由 信息 添加 到 RouteTable.Routes 静 
态 属性 中 ， 这 个 属性 是 一 个 RouteCollection, 


例如 ， 示 例 11-1 展示 了 ASP.NET MVC 项 目 模 板 定 义 的 默认 映射 ， 这 些 信息 通常 定义 在 
global.asax 文件 中 。 


示例 11-1: ASP.NET MVC 默认 路 由 配置 
protected void Application_Start() 


{ 
RegisterRoutes(RouteTable. Routes); 
} 
public static void RegisterRoutes(RouteCollection routes) 
{ 
routes. IgnoreRoute("{resource}.axd/{*pathInfo}"); 
routes .MapRoute( 
"Default", // 路 由 名 
"{controller}/{action}/{id}", // 带 参数 的 URL 
new { controller = "Home", action = "Index", 
id = UrlParameter.Optional } 
); 
} 





静态 属性 RouteTable.Routes 定义 了 一 个 路 由 集合 ， 对 应 用 程序 全 局 有 效 ， 具 体 的 路 由 就 
添加 在 这 个 路 由 集合 中 。 示 例 11-1 中 使 用 了 MapRoute 方法 添加 路 由 ， 这 个 方法 并 不 是 路 
由 集合 的 实例 方法 ， 而 是 ASP.NET MVC 中 引入 的 一 个 扩展 方法 ， 用 于 添加 MVC 相关 的 

















注 1: Web Forms 也 可 以 通过 RouteCollection.MapPageRoute 方法 ， 使 用 路 由 功能 。 
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路 由 。 我 们 随后 将 看 到 ，Web API 也 使 用 类 似 的 方式 。 
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@ 11-2; ASP.NET 路 由 类 





图 11-2 展示 了 参与 ASP.NET 路 由 过 程 的 一 些 类 。 通 用 的 路 由 概念 定义 为 抽象 类 RouteBase, 
类 中 包含 GetRouteData 实例 方法 。GetRouteData 检查 一 个 请 求 上 下 文 ( 即 请 求 URI) BA 
与 路 由 匹配 ， 如 果 匹 配 ， 就 返回 包含 一 个 RouteData 实例 ， 其 中 包含 一 个 简单 的 处 理 程序 
工厂 IRouteHandler 。 此 外 ，RouteData 还 包含 由 匹配 过 程 产生 的 一 组 额外 的 值 。 例 如 : 示 
例 11-1 中 的 Default 路 由 所 匹配 的 HTTP 请求， 产生 的 RouteData 4 4) controller 和 
action 路 由 值 。 




















RouteBase 类 还 包含 GetVirtualPath 方法 ， 用 于 执行 反 向 查找 给 出 一 组 值 ， 返 回 一 个 匹 
配 该 路 由 并 能 产生 这 些 值 的 URI。 


抽象 类 RouteBase 并 不 与 具体 的 路 由 匹配 过 程 相 关联 ， 而 是 由 具体 的 派生 类 进行 定制 。 
Route 是 RouteBase 的 派生 类 之 一 ， 定 义 了 一 个 具体 的 匹配 过 程 ， 该 过 程 用 到 如 下 元 素 : 


e 一 个 URI 模板 ,定义 URI 结构 (例如 : "{controller}/{action}/{id}") ; 

。 一 组 默认 值 (例如 :new { controller = "Home", action = "Index", id = UrlParameter. 
Optional }) ; 

。 一 组 附加 约束 。 
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URI 模板 既定 义 了 匹配 该 路 由 的 URI 所 必须 具有 的 结构 ， 也 定义 了 占 位 符 ， 用 于 从 URI 
路 径 段 中 获取 路 由 数据 。 


对 于 一 个 请 求 ， 附 加 在 PostResolveRequestCache 管道 事件 上 的 UrlRoutingModule 执行 路 
由 选择 逻辑 。 对 每 个 请 求 ， 这 个 模块 将 当前 的 请 求 与 全 局 的 RouteTable.Routes 集合 中 的 
路 由 进行 匹配 ， 如 果 匹 配 成 功 ， 相 关 的 HTTP 处 理 程序 就 会 映射 到 当前 的 请 求 。 因 此 ， 在 
管道 未 端 ， 应 用 程序 会 将 请 求 的 处 理 委托 给 这 个 处 理 程序 。 例 如 ， 由 MVC 的 MapRoute H“ 
展 方法 添加 的 所 有 路 由 都 映射 到 一 个 特殊 的 MvcHandler , 


11.1.3 Web API 路 由 

ASP.NET 路 由 模型 和 基础 结构 依赖 于 遗留 的 ASP.NET 模型 ， 即 : 通过 HttpContext 示例 
来 表示 请 求 和 响应 。Web API 虽然 使 用 类 似 的 路 由 概念 ， 但 是 也 使 用 新 的 HTTP 类 模型 ， 
因此 定义 了 一 组 新 的 路 由 相关 类 和 接口 ， 如 图 11-3 所 示 。 











IHttpRoute 办 
Interface 

| 

日 properties 


图 Constraints { get; } : IDictionary<string, object> 
&}  DataTokens { get; } : IDictionary<string, object> 
&} Defaults { get: } : IDictionary<string, object> 
&F Handler { get; } : HttpMessageHandler 
©} = RouteTemplate { get; } : string 
= Methods 
=® GetRouteData(string virtualPathRoot, HttpRequestMessage request) : IHttpRouteData 
=$ ~GetVirtualPath(HttpRequestMessage request, IDictionary<string, object> values) : IHttpVirtualPathData 
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11-3: Web API 路 由 类 





IHttpRoute 表示 一 个 Web API 路由， 与 经 典 的 ASP.NET Route 类 具有 类 似 特 征 ， 包 括 : 





e GetRouteData 方 法， 接收 一 个 HTTP 请 求 和 虚拟 根 路 人 符 ， 返 回 一 个 包含 值 字典 的 
IHttpRouteData; 

e GetVirtualPath 方法 ， 接 收 一 个 值 字典 和 一 个 请 求 消 息 ， 返 回 一 个 带 有 URI 的 
IHttpViruaLPath ; 

。 一 组 属性 ， 包 含 路 由 模板 、 默 认 路 由 和 约束 。 


Web API 的 一 个 重要 区 别 是 ，Web API 使 用 新 的 HTTP 类 模型 一 一 特别 是 HttpRequest 
Message 和 HttpMessageHanlder 类 而 不 是 旧 的 ASP.NET 类 ， 如 HttpRequest 和 
IHttqHandler , 








Web API 还 定义 了 一 种 方法 ， 在 经 典 的 ASP.NET 路 由 基础 结构 之 上 使 用 新 路 由 类 (如 图 
11-4 所 示 )。 当 Web API 托管 在 ASP.NET 之 上 时 ， 使 用 这 个 内 部 适 配 层 ， 可 以 让 我 们 在 一 
个 HTTP 应 用 程序 内 同时 使 用 新 旧 两 种 路 由 。 





















































| HostedHttpRouteCollection © AA outecollection | | Routecollection 
Class - Class 
+ HttpRouteCollection + Collection<RouteBase> 
g=] 
& HttpRoute | 
IHttpRoute 2 | OriginalRoute | | Route 
Interface — j Class 
(a + RouteBase 
~an 2 
Y IHttpRoute 
| HostedHttpRoute © ) HttpWebRoute 
Class Class 
+ Route 























图 11-4; Web API 路 由 适 配 类 


HostedHttpRouteCollection 类 是 一 个 适配器 ， 在 经 典 的 ASP.NET RouteCollection 上 提供 
一 个 ICollection<IHttpRoute> 接口 。 如 果 一 个 新 的 IHttpRoute 加 入 这 个 集合 ，HostedHttp 
RouteCollection 将 其 包装 成 一 个 特殊 的 适配器 Route (HttpWebRoute)， 并 将 其 添加 到 
ASP.NET 的 路 由 集合 中 。 














通过 这 种 方式 ， 这 个 全 局 的 ASP.NET 路 由 集合 可 以 同时 包含 经 典 的 路 由 ， 和 新 Web API 
路 由 的 适配器 。 
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11.1.4 全 局 配置 


当 托 管 在 ASP.NET 之 上 时 ，Web API 相关 的 配置 定义 在 一 个 HttpConfiguration 单 例 对 象 
中 ， 可 以 通过 静态 的 GlobalConfiguration.Configuration 属性 访问 。 在 示例 11-2 中 ， 这 
个 单 例 对 象 用 做 默认 路 由 配置 的 参数 。 


示例 11-2: ASP.NET Web API 默认 路 由 配置 


// config 等 同 GlobalConfiguration.Configuration 
config.MapHttpAttributeRoutes(); 
config.Routes .MapHttpRoute( 
name: "DefaultApi", 
routeTempLate: "“api/{controller}/{id}", 
defaults: new { id = RouteParameter.Optional } 


)3 
这 个 单 例 配置 的 Routes 属性 指向 一 个 HostedHttpRouteCollection， 其 中 封装 了 全 局 的 
RouteTable.Routes 集合 (如 图 11-5 所 示 )。 也 就 是 说 ， 所 有 添加 到 Globalconfiguration. 
Configuration.Routes 的 Web API 路 由 ， 最 后 都 会 作为 经 典 的 ASP.NET 路 由 ， 添 加 到 全 
局 的 RouteTable.Routes 集合 中 。 tk, 4 UrlRoutingModule 尝试 寻找 一 个 匹配 路 由 时 ， 
这 些 Web API 路 由 也 会 纳入 寻找 范围 。 
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由 ASP.NET MVC 配置 添加 的 路 由 关联 到 MvcHanlder 类 。 ieee 在 管道 末端 ， 匹 配 
这 些 路 由 的 所 有 请 求 都 会 委托 给 这 个 MvcHandler 处 理 。 然 后 ， 这 个 特殊 的 处 理 程序 会 执行 


MVC 相关 的 请 求 处 理 ， 即 : 选择 控制 器 并 调用 映射 操作 。 


















































Web API 的 场景 非常 类 似 : 由 GlobalConfiguration.Configuration.Routes 添加 的 路 由 关 
联 到 HttpControllerHandler， 最 终 由 这 个 HttpControllerHandler 处 理 匹 配 这 些 Web API 


路 由 的 所 有 请 求 。 


图 11-6 展示 了 这 一 特点 ，RouteTable.Routes 集合 既 包 含 MVC 路 由 ， 也 包含 Web API 路 由 。 
日 是 ， 请 注意 MVC 路 由 关联 到 MvcHandler， 而 Web API 路 由 关联 到 HttpController Handler, 
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11-6; RouteTable.Routes BE MVC 路 由 ， 也 包含 Web API 路 由 


11.1.5 Web API ASP.NET 处 理 程 序 


我 们 刚才 介绍 过 ， 匹 配 Web API 路 由 的 所 有 ASP.NET 请 求 都 会 由 新 的 HttpController 
Handler 进行 处 理 。 这 个 处 理 程序 的 BeginProcessRequest 方法 会 执行 以 下 操作 。 



































。 首先 ， 当 处 理 第 一 个 请 求 时 ， 这 个 处 理 程序 会 通过 GlobalConfiguration.Configuration, 
延迟 生成 一 个 HttpServer 单 例 。 这 个 服务 器 实例 包含 了 消息 处 理 程序 管道 ， 其 中 包括 
控制 器 分 发 处 理 程序 。 





























。 接 下 来 ， 处 理 程序 将 当前 HttpContext 中 的 ASP.NET HttpRequest 消息 转换 成 一 个 新 的 
HttpRequestMessage 实例 。 

。 最 后 ， 处 理 程序 将 这 个 HttpRequestMessage 推送 到 HttpServer 实例 ， 开 始 Web API 处 
理 中 与 平台 无 关 的 阶段 ， 这 一 阶段 由 消息 处 理 程序 管道 和 控制 器 层 组 成 。 


本 地 ASP.NET 消息 表示 和 Web API 表示 之 间 的 转换 ， 是 通过 一 个 服务 对 象 (service object) 
配置 的 ， 这 个 服务 对 象 实现 IHostBufferPoLicySeLector 接口 。IHostBufferPoLicySeLector 
接口 有 两 个 方法 : UseBufferedInputStream 和 UseBuffered0utputStream， 定 义 消 息 正文 是 否 
应 该 进行 缓冲 。HttpControtLterHandtLer 从 全 局 配置 请 求 得 到 这 个 服务 对 象 ， 用 于 判断 : 


e HttpRequestMessage 内 容 使 用 的 请 求 输入 流 是 ASP.NET 缓冲 输入 ， 还 是 流 输 入 ; 

e HttpResponseMessage 内 容 是 否 写 人 一 个 ASP.NET 缓冲 输出 流 。 

默认 注册 的 Web 宿主 策略 总 是 使 用 缓冲 输入 流 。 对 于 输出 流 ， 上 默认 策略 基于 返回 的 
HttpResponseMessage 属性 ， 使 用 如 下 规则 。 








。 如 果 内 容 长 度 已 知 ， 那 么 就 明确 设置 Content-Length， 不 使 用 分 块 。 因 为 内 容 长 度 已 经 
确定 ， 无 需 缓 冲 即 可 进行 传输 。 

。 如 果 内 容 类 为 StreamContent， 那 么 只 有 当 底层 流 不 提供 长 度 信息 时 ， 才 使 用 分 块 传输 
编码 。 

。 如 果 内 容 类 为 PushstreamContent， 那 么 就 使 用 分 块 传输 编码 。 

。 如 果 不 属 于 上 述 三 种 情况 ， 则 在 内 容 传 输 前 进行 缓冲 ， 以 判断 其 长 度 ， 不 使 用 分 块 。 
































将 ASP.NET HttpRequest 消息 转换 成 一 个 新 的 HttpRequestMessage 实例 的 操作 ， 不 仅仅 处 
理 请 求 消息 的 信息 ， 还 获取 一 组 托管 上 下 文 信息 ， 插 入 HttpRequestMessage.Properties 字 
典 中 。 这 一 信息 的 内 容 有 : 


。 客户 端 使 用 的 证 书 (如 果 请 求 是 在 使 用 客户 端 认 证 的 SSL/TLS 连接 上 完成 的 ) ; 

。 一 个 布尔 值 属性 ， 表 明 请 求 是 否 来 自 同 一 机 器 ; 

。 一 个 标识 (如果 开 启 了 定制 错误 )。 

请 注意 ， 这 个 信息 并 非 来 自 请 求 消息 ， 而 是 由 托管 基础 结构 提供 ， 反 映 了 托管 上 下 
文 ， 如 连接 特征 。 例 如 : 作为 属性 添加 到 消息 的 客户 端 认 证 信息 ， 可 以 通过 扩展 方法 
GetClientCertificate 公开 访问 。 其 余 的 信息 专门 供 Web API 运行 时 使 用 。 

















ASP.NET Web API 的 2.0 版 本 引入 了 请 求 上 下 文 (request context) 的 概念 ， 用 于 组 织 所 有 
的 上 下 文 信息 。 新 的 HttpRequestContext 类 不 再 包含 各 种 无 类 型 的 请 求 属性 ， 而 是 用 下 再 
一 组 属性 来 代表 上 下 文 信息 ; 

















。 客户 端 证 书 ; 
。 虚拟 根 路 径 ， 
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。 请 求 身 份 信息 。 


Web API ASP.NET 处 理 程 序 创建 一 个 WebHostHttpRequestContext 实例 (WebHostHttp 
RequestContext 派生 自 HttpRequestContext)， 在 其 中 填 入 请 求 的 上 下 文 信息 。 其 上 层次 就 
可 以 通过 这 个 请 求 的 GetRequestContext 扩展 方法 ,访问 这 一 信息 。 

















图 11-7 图 形 化 地 概括 了 Web 托管 的 基础 结构 ， 展 示 了 路 由 解析 过 程 ， 以 及 分 发 至 HttpServer 
实例 的 操作 。 总 结 如 下 。 








e Web API 可 以 在 ASP.NET 基础 结构 之 上 进行 托管 ， 与 其 他 框架 (如 ASP.ENT MVC 或 
Web Forms) 共享 同样 的 应 用 程序 。 

。 ASP.NET 路 由 基础 结构 用 于 识别 绑 定 到 Web API 运行 时 的 请 求 。 这 些 请 求 交 由 特殊 的 
处 理 程序 处 理 ， 从 本 地 HTTP 表示 转换 为 新 的 System.Net.Http 模型 对 象 。 

。 我 们 可 以 在 应 用 程序 开始 时 进行 Web API 配置 ,通常 做 法 是 在 global.asax.cs 文件 的 
Application_Start 方法 中 添加 代码 ， 使 用 Globalconfiguration.HttpConfiguration 单 
例 对 象 进 行 配置 。 

。 使 用 Web 托管 方式 时 ， 我 们 必须 在 底层 的 宿主 上 ， 而 非 通 用 的 Web API 上 进行 一 些 配 
置 定 义 。 例 如 : 我 们 可 以 使 用 US 管理 器 ， 配 置 安全 连接 使 用 SSL 或 TLS。 
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11.2 HHE 


Web API 也 包含 自 托管 ( 即 在 任何 Windows 进程 上 托管 ， 例 如 : 控制 台 应 用 程序 或 者 
Windows 服务 ) 的 适 配 层 。 示 例 11-3 展示 了 自 托 管 的 典型 代码 。 


示例 11-3: AE 
var config = new HttpSelfHostConfiguration("http://localhost:8080") ; 
config.Routes.MapHttpRoute("default", "{controller}/{id}", 
new { id = RouteParameter.Optional }); 
var server = new HttpSelfHostServer (config); 
server .OpenAsync().Wait(); 
Console.WriteLine('"Server is opened"); 
Console.ReadLine(); 
server .CloseAsync().Wait(); 


请 注意 ， 采 用 自 托管 方式 时 ， 我 们 必须 明确 地 创建 、 配 置 并 启动 一 个 服务 器 实例 。 这 
与 Web 托管 方式 不 同 。 采 用 Web 托管 时 ， 所 需 的 HttpServer 实例 是 由 ASP.NET 处 
里 程序 隐 式 延迟 创建 的 。 还 需要 注意 的 是 ， 示 例 11-3 使 用 了 自 托管 场景 专用 的 类 。 
HttpSelfHostServer 类 派生 自 通 用 类 Httpserver， 由 一 个 HttpSelfHostConfiguration 进行 
配置 ， 这 个 HttpSelfHostConfiguration 派生 自 通 用 类 HttpConfiguration。 托 管 的 基地 址 
明确 定义 在 自 托管 配置 中 。 图 11-8 展示 了 这 些 类 之 间 的 关系 。 
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在 Web API 的 1.0 ht Æ F, HttpSelfHostServer 内 部 使 用 了 WCF (Windows Communic- 
ation Foundation) 信道 栈 层 ， 从 底层 HTTP 基础 结构 获得 请 求 消 息 。 下 一 节 将 简要 介绍 
WCE 的 高 层 架 构 ， 以 便 在 此 基础 上 ， 进 行 Web API 自 托 管 特点 的 介绍 。 


11.2.1 WCF 架构 
WCF 架构 分 为 两 层 : 信道 栈 层 和 服务 模型 层 (如 图 11-9 所 示 )。 
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图 11-9: WCF 架构 


底层 的 信道 栈 层 由 一 个 信道 栈 组 成 ， 与 经 典 的 网 络 协 议 栈 行为 方式 类 似 。 这 些 信道 分 为 两 
类 : 传输 信道 和 协议 信道 。 协 议 信道 处 理 在 栈 中 向 上 和 向 下 流动 的 消息 。 协 议 信道 的 典型 
用 法 有 : 在 发 送 端 添加 数字 签名 ,以 及 在 接收 端 验 证 这 些 签 名 。 传 输 信道 处 理 与 传输 媒 
介 的 交互 (例如 : TCP, MSMQ 和 HTTP)， 即 传输 和 发 送 消 息 。 传 输 信道 使 用 编码 程序 
(encoder)， 在 传输 媒介 字 节 流 和 消息 实例 之 间 进 行 转换 。 


上 层 的 服务 模型 层 执行 销 息 和 方法 调用 之 间 的 交互 ， 处 理 如 下 任务 : 


。 将 收 到 的 消息 转换 成 为 一 个 参数 序列 ， 

。 获得 要 使 用 的 服务 实例 ; 

。 选择 要 调用 的 方法 ; 

。 获得 调用 方法 的 线程 。 

信道 栈 层 的 具体 组 织 由 绑 定 进行 描述 ， 如 图 11-10 所 示 。 一 个 绑 定 是 绑 定 元 素 (binding 


element) 的 一 个 有 序 集合 ， 其 中 每 个 元 素 大 致 描述 一 个 信道 或 编码 程序 。 第 一 个 绑 定 元 素 
描述 上 层 信 道 ， 最 后 一 个 元 素描 述 底层 信道 ， 底 层 信 道 总 是 一 个 传输 信道 。 
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B 11-10: 绑 定 、 绑 定 元 素 以 及 信道 











11.2.2 HttpSelfHostServer 类 


HttpSelfHostServer 类 实现 了 一 个 自 托管 的 Web API 服务 器 。 如 示例 11-3 中 的 代码 所 
示 ， 这 个 自 托管 Web API 服务 器 使 用 HttpSeLfHostConfiguration 类 的 一 个 实例 进行 配置 ， 
HttpSelfHostConfiguration 类 派生 自 较 为 通用 的 HttpConfiguration， 加 入 了 与 自 托管 场景 
相关 的 特殊 配置 属性 。 


HttpSelfHostServer 内 部 创建 了 一 个 WCF 信道 栈 ， 使 用 这 个 信道 栈 监 听 HTTP 请 求 。Web 
API 自 托管 支持 引入 了 新 的 HttpBinding 类 ， 描 述 这 个 信道 栈 。 


当 启 动 服务 器 时 ，HttpSeLfHostServer.0penAsync 方法 创建 一 个 HttpBinding 实例 ， 让 
HttpSelfConfiguration 实例 配置 这 个 HttpBinding 实例 ， 然 后 使 用 这 个 绑 定 异步 创建 WCE 
信道 栈 。HttpSeLfHostServer.0penAsync 还 创建 一 个 “ 泵 ”"， 不 断 从 这 个 信道 栈 中 拉 取 消息 ， 
将 消息 转换 为 HttpRequestMessage 实例 ， 并 将 这 些 新 请 求 推 送 到 消息 处 理 程序 管道 中 。 





与 Web 托管 的 情况 类 似 ， 创 建 的 HttpRequestMessage 带 有 一 个 HttpRequestContext 实例 ， 
其 中 包含 了 从 托管 上 下 文 得 到 的 一 组 属性 。 当 客户 端 认证 使 用 TLS/SSL 时 ， 这 组 属性 包含 
客户 端 认 证 信息 。 

从 信道 栈 拉 取信 息 的 泵 还 负责 获得 返回 的 HttpResponseMessage， 将 其 写 入 信道 栈 中 。 对 于 
响应 流 ， 自 托管 与 Web 托管 处 理 方式 不 同 。 自 托管 要 么 使 用 明确 的 Content-Length 标 头 ， 
要 么 使 用 分 块 传输 编码 ， 选 择 基 于 如 下 HttpSelfHostConfiguration 选项 : 





public TransferMode TransferMode {get; set;} 


如 果 选 项 值 为 TransferMode.Buffered， 那 么 不 管 TryComputeLength 的 返回 值 或 ContentLength 
标 头 属性 值 是 什么 ， 宿 主 总 是 明确 设置 Conent-Length。 也 就 是 说 ， 如 果 HttpContent 实例 没 
有 提供 长 度 信息 ， 那 么 宿主 会 在 内 存 中 缓冲 全 部 内 容 ， 以 判断 其 长 度 ， 然 后 才 发 送 内 容 。 另 
外 ， 如 果 选 项 值 为 TransferMode.Streaned， 那 么 即便 已 知 内 容 长 度 ， 和 宿主 也 总 是 使 用 分 块 
传输 。 
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11.2.3 HttpSelfHostConfigurationZ& 


我 们 前 面 提 到 ，HttpSelfHostServer 中 定义 的 HttpSeLfHostConfiguration 负责 配置 内 部 使 
用 的 HttpBinding, HttpBinding 又 配置 WCF 消息 信道 。 因 此 ，HttpSeLfHostConfiguration 
类 包含 一 组 公共 属性 (参见 示例 11-4) ， 反 映 了 这 个 内 部 实现 的 细节 ( 即 基于 WCF 编程 模 
型 )。 例 如 : MaxReceivedMessageSize (在 常用 的 WCF BasicHttpBinding 类 中 也 有 这 个 属 
性 ) 定义 了 接收 到 消息 的 最 大 长 度 。 另 一 个 例子 是 X569CertificateValidator 属性 ， 这 个 
属性 基于 System.IdentityModel 程序 集中 的 一 个 类 ， 用 于 配置 SSL/TLS 连接 上 收 到 的 客户 
端 认 证 。 











示例 11-4: HttpSelfHostConfiguration 属性 
public class HttpSelfHostConfiguration : HttpConfiguration 


{ 
public Uri BaseAddress {get;} 
public int MaxConcurrentRequests {get;set;} 
public TransferMode TransferMode {get;set;} 
public HostNameComparisonMode HostNameComparisonMode {get;set;} 
public int MaxBufferSize {get;set;} 
public long MaxReceivedMessageSize {get;set;} 
public TimeSpan ReceiveTimeout {get;set;} 
public TimeSpan SendTimeout {get;set} 
public UserNamePasswordValidator UserNamePasswordValidator {get;set;} 
public X509CertificateValidator X509CertificateValidator {get;set;} 
public HttpClientCredentialType ClientCredentialType {get;set;} 


// 为 清晰 起 见 ， 省 略 其 他 成 员 





进行 内 部 自 托管 行为 的 配置 的 另 一 种 方法 是 创建 HttpSeLfHostConfiguration 的 一 个 派 
生 类 ， 过 载 0nConfigureBinding 方 法 。 这 个 方法 接收 HttpSelfHostserver 内 部 创建 的 
HttpBinding 实例 ， 可 以 在 其 用 于 配置 WCF 信道 栈 之 前 ， 修 改 绑 定 设置 。 图 11-11 展示 了 
自 托管 架构 ， 特 别 是 WCF 信道 栈 的 使 用 ， 以 及 配置 和 WCF 绑 定 之 间 的 关系 。 


Web API 自 托 管 依 赖 于 WCEF， 既 有 好 处 ， 也 有 缺点 。 主 要 的 好 处 是 ， 我 们 可 以 使 用 WCF 
HTTP 绑 定 的 大 部 分 功能 ， 例 如 : 消息 限制 message limiting), Yii (throttling) 和 超时 
(timeout)。 主 要 缺点 是 ， 对 WCF 的 依赖 是 通过 HttpSelfHostConfiguration 公共 接口 ， 也 
就 是 这 个 接口 的 一 些 属 性 提供 的 。 


请 注意 ， 消 息 泵 从 底层 信道 栈 获取 消息 ， 并 将 其 转换 成 为 HttpRequestMessage 实例 ， 之 后 
才 将 其 推送 给 HttpServer。 
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图 11-11: 自 托 管 架构 


11.2.4 URL 预 留 和 访问 控制 
如 果 从 非 管 理 员 账 号 启动 一 个 自 托管 Web 服务器， 你 通常 会 得 到 如 下 错误 


HTTP could not register URL http://+:8080/. 
Your process does not have access rights to this namespace 


为 什么 会 发 生 这 个 错误 ? 我 们 该 如 何 解决 这 个 问题 ?为 了 回答 这 些 问题 ， 我 们 需要 对 
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HTTP 的 低层 处 理 架 构 进行 一 个 简要 的 介绍 。 





在 Windows 中 ， 一 个 内 核 模 式 的 设备 驱动 程序 ，HTTP.sys， 监 听 HTTP ik. IS 和 WCF 
自 托管 传输 信道 都 通过 用 户 模 式 的 HTTP 服务 器 API， 使 用 这 个 内 核 模 式 的 驱动 。 服 务 器 
应 用 程序 使 用 这 个 API， 注 册 一 个 指定 URL 命名 空间 的 请 求 处 理 。 例 如 : 如 果 运 行 示例 
11-3， 自 托管 应 用 程序 就 会 注册 http: //+:8080 命名 空间 。 主 机 名 中 的 + 是 一 个 强 通配符 
(strong wildcard) ， 告 诉 HTTP.SYS 考虑 来 自 所 有 网 络 适 配器 的 请 求 。 但 是 ， 这 个 注册 操 
作 受 到 访问 权限 的 控制 ， 默 认 情 况 下 ， 只 有 具有 管理 员 权 限 的 进程 村 有 权 执 行 这 个 注册 操 
作 。 之 前 看 到 的 错误 就 是 由 于 这 个 原因 导致 的 。 


要 解决 这 个 问题 ， 一 个 办 法 是 使 用 管理 员 权限 账号 启动 自 托管 应 用 程序 。 但 是 ， 使 用 管理 
员 权 限 运 行 服务 器 通常 不 是 一 个 好 主意 。 更 好 的 解决 办 法 是 ， 赋 给 运行 应 用 程序 的 账号 所 
需 的 权限 。 为 此 ， 我 们 可 以 为 该 账号 预 贸 URL 命名 空间 ， 人 允许 相关 应 用 程序 注册 预 留 命名 
空间 里 的 URL。 我 们 可 以 使 用 命令 行 工 具 netsh (这 个 工具 需要 管理 员 权 限 )， 进 行 预 留 : 













































































netsh http add urlacl url=http://+:8080/ user=domain\user 


其 中 的 domain\user 值 应 该 替换 为 运行 自 托管 应 用 程序 的 用 户 标识 。 这 个 用 户 标 识 也 可 以 
是 Windows 的 特殊 账号 ， 例 如 : network service 通常 用 于 运行 Windows 服务 中 托管 的 
HTTP 服务 器 。 如 果 使 用 Windows 的 特殊 账号 ，domain\user 可 以 赫 换 为 network service 


BY local service, 


11.3 用 OWIN 和 Katana 托 管 Web API 


在 本 章 开 篇 ， 我 们 就 了 解 到 ，ASP.NET Web API 是 以 与 宿主 无 关 的 方式 构建 的 ， 这 种 特 
性 使 得 Web API 既 可 以 在 传统 的 ASP.NET FU IS 宿主 中 运行 ， 也 可 以 在 一 个 定制 的 进程 
( 自 托管 ) 中 运行 。ASP.NET Web API 与 宿主 无 关 的 这 一 特性 ， 给 Web API 的 创建 和 运行 
创造 了 新 的 机 会 ， 也 带 来 了 新 的 挑战 。 例 如 : 在 很 多 情况 下 ， 开 发 者 并 不 希望 为 了 自 托管 
Web API 而 编写 一 个 定制 的 控制 台 应 用 程序 或 者 Windows 服务 。 很 多 具有 框架 (如 Node. 
js 或 Sinatra) 使 用 经 验 的 开发 者 ， 和 希望 能 够 将 应 用 程序 托管 在 一 个 已 有 的 可 执行 程序 中 。 
而 且 ， 在 如 今 的 Web 应 用 程序 中 ， 一 个 Web API 通常 只 是 多 个 组 件 中 的 一 个 。 甚 他 组 件 
A: 服务 器 端的 标记 生成 框架 (如 ASP.NET MVC)、 静 态 服务 器 文件 ， 以 及 实时 消息 框架 
(如 SignalR)。 此 外 ， 一 个 应 用 程序 可 能 由 很 多 更 小 的 组 件 构成 ， 每 个 组 件 关 注 具体 的 任 
务 ， 例 如 : 认证 或 者 日 志 。 虽 然 Web API 现在 提供 了 不 同 的 托管 选项 ， 但 是 一 个 Web API 
宿主 不 能 同时 托管 前 面 提 到 的 其 他 组 件 ， 也 就 是 说 ， 如 今 的 Web 应 用 程序 中 ， 每 个 不 同 的 
技术 都 需要 有 自己 单独 的 宿主 。 在 使 用 Web 托管 时 ，IIS 和 ASP.NET 可 以 请 求 管道 屏蔽 这 
一 限制 ， 但 是 在 自 托管 方式 下 ， 这 个 问题 就 变 得 非常 明显 。 


我 们 实际 需要 的 是 一 种 抽象 方式 ， 使 很 多 不 同类 型 的 组 件 形 成 单个 Web 应 用 程序 ， 然 后 使 












































整个 应 用 程序 按照 其 特定 的 需求 和 部 署 环境 ， 运 行 在 各 种 服务 器 和 宿主 之 上 。 


11.3.1 OWIN 


OWIN (Open Web Interface for .NET，.NET 开放 Web 接口 ， 参 见 http://owin.org/) 是 开放 
源 代码 社区 创建 的 一 个 标准 ， 定 义 了 服务 器 和 应 用 程序 组 件 如 何 进行 交互 。 创 建 OWIN 的 
目的 ， 是 为 了 改变 NET Web 应 用 程序 的 构建 方式 一 一 从 应 用 程序 作为 单个 大 型 框架 扩展 
的 方式 ， 转 变 为 小 模块 松 耦 合 的 方式 。 








为 了 实现 这 一 目标 ，OWIN 将 服务 器 和 应 用 程序 组 件 之 间 的 交互 简化 为 一 个 简单 接口 ， 称 
为 应 用 程序 委托 或 app func.: 





Func<IDictionary<string, object>, Task> 


这 个 接口 是 OWN 兼容 服务 器 或 模块 (也 称 为 中 间 件 ) 需要 满足 的 唯一 要 求 。 此 外 ， 因 为 
文 个 应 用 程序 委托 只 使 用 了 少数 儿 个 NET 类 型 ，OWIN 应 用 程序 更 容易 移植 到 不 同 版 本 
的 框架 ， 甚 至 不 同 的 平台 上 ， 例 如 : Mono 项 目 。 

















这 个 应 用 程序 委托 定义 了 一 个 交互 ， 通 过 这 个 交互 ， 组 件 使 用 一 个 字典 对 象 ( 称 为 环境 或 
Hh ATID 接收 所 有 状态 《包括 服务 器 状态 、 应 用 程序 状态 和 请 求 状态 )。 因 为 一 个 基于 
OWIN 的 应 用 程序 应 该 是 异步 的 ， 所 以 这 个 应 用 程序 委托 在 执行 完工 作 ， 完 成 环境 字典 修 
改 后 ， 返 回 一 个 Task 实例 。OWIN 标准 定义 了 环境 字典 中 可 能 或 必须 存在 的 几 个 键 / 值 
(如 表 11-1 所 示 )。 除 此 之 外 ， 任 何 OWIN 服务 器 或 宿主 可 以 在 这 个 环境 字典 中 提供 自己 
的 条 目 ， 这 些 条 目 可 以 供 任何 其 他 中 间 件 使 用 。 


表 11-1: 请 求 数据 的 环境 条 目 










































































必需 键 名 值 说 明 

是 "owin.RequestBody" 包含 请 求 正文 (如 果 有 ) 的 stream。 如 果 没 有 请 求 正文 ，Stream. 
Null 可 以 用 做 占 位 符 

是 "owin.RequestHeaders" 请 求 标 头 的 IDictionary<string, string[]> 

是 "owin.RequestMethod" 包含 请 求 的 HTTP 请 求 方法 的 字符 串 (例如 : "GET" 和 "POST") 

是 “owin.RequestPath" 包含 请 求 路 径 的 字符 串 。 此 路 径 必 须 是 应 用 程序 委托 “ 根 ” 的 相对 
路 径 

是 "owin.RequestPathBase" 字符 串 ， 包 含 请 求 路 径 中 对 应 于 应 用 程序 委托 “ 根 ” 的 部 分 

是 "owin.RequestProtocol" 包含 协议 名 和 协议 版 本 的 字符 串 (An: "HTTP/1.0" 或 "HTTP/1.1") 

是 "owin.RequestQuery String" 字符 串 ， 包 含 HTTP 请 求 URI 的 请 求 字 符 串 部 分 ， 不 含 前 导 “?” (fil 
如 : "foo=bar&baz=quux" ) 。 这 个 值 可 能 为 空 字符 串 

是 “owin.RequestSchene" 包含 请 求 所 用 URI 方 案 的 字符 串 〈 例 如 ，"http" 和 "https") ， 参 见 
URI Scheme 

















除了 将 服务 器 和 应 用 程序 的 交互 定义 在 这 个 应 用 程序 委托 和 环境 字典 中 ，OWIN 标准 还 提供 
了 宿主 和 服务 one 些 指导 意见 ， 例 如 : 如 何 处 理 URI 和 HTTP 标 头 ， 应 用 程序 启动 ， 
以 及 错误 处 理 。 这 个 应 用 程序 委托 非常 简单 ， 松 散 类 型 的 环境 字典 十 分 灵活 ， 二 者 结合 在 
一 起 ， 下 并 将 其 组 合 为 单个 应 用 程序 管道 。 
ASP.NET 的 下 一 个 版 本 就 将 集成 几 个 这 样 的 专门 组 件 ， 第 15 章 会 对 此 进行 更 多 的 介绍 。 


























你 可 以 在 线 获得 完整 的 OWIN 规范 (http://owin.org/spec/owin-1.0.0.html ) 。 


11.3.2 Katana 项 目 

OWIN 规范 定义 了 服务 器 和 应 用 程序 组 件 如 何 进行 交互 ， 以 处 理 Web 请 求 ，Katana 则 是 一 组 
符合 OWIN 规范 的 组 件 ， 这 些 组 件 由 Microsoft 开发 ， 作 为 开源 软件 发 布 !:。 如 图 11-12 所 示 ， 
Katana 项 目 组 件 按 架构 层 进行 组 织 。 图 11-13 展示 了 流 经 不 同 层次 和 组 件 的 HTTP 数据 。 






































用 户 代码 


框架 /中 间 件 Authentication 


Diagnostics 
CORS 
服务 器 SystemWeb 


HttpListener 





宿主 OwinHost.exe 











& 11-12; Katana 组 件 架构 以 及 组 件 示例 





应 用 程序 
ASP.NET Web API 


(Microsoft.AspNet.WebApi.Owin) 


== J 


11-13: 流 经 运行 于 OWIN 管道 和 Katana 宿主 上 的 ASP.NET Web API 应 用 程序 的 HTTP 数据 

















注 1: 除了 Microsoft Katana 组 件 ， 许 多 流行 的 开源 Web 框架 (如 NancyFX、FUBU、ServiceStack 等 ) 都 
可 以 运行 在 OWIN 管道 中 。 
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Kanata 组 件 分 为 三 层 : 宿主 、 服 务 器 和 中 间 件 。 各 层 组 件 的 功能 如 下 。 





Ea 

宿主 开始 和 管理 进程 。 宿 主 负责 启动 一 个 进程 ， 并 初始 化 OWIN 规范 第 四 节 (http:/ 
owin.org/spec/owin-1.0.0.html#_4._Application_Startup) 中 提出 的 启动 序列 。 

服务 器 


服务 器 监听 HTTP 请 求 ， 确 保 环 境 字典 中 的 值得 到 正确 设置 ， 并 为 中 间 件 组 件 管 道中 的 
第 一 个 中 间 件 调用 其 应 用 程序 委托 。 








中 间 件 
中 间 件 是 对 请 求 或 响应 执行 不 同 任务 的 组 件 。 这 些 组 件 可 以 执行 很 小 的 任务 ， 例 如 : 进 
页 





XLE 
行 压缩 或 者 实施 HITPS， 也 可 以 作为 整个 框架 〈 例 如: ASP.NET Web API) 的 适配器 
组 件 组 成 一 个 管道 结构 ， 其 中 每 个 组 件 都 持 有 指向 管道 中 下 一 个 组 件 的 引用 。 宿 主 负责 
在 其 启动 序列 中 构建 这 个 管道 。 




















如 果 以 传统 的 基于 框架 的 方法 运行 Web 应 用 程序 ， 那 么 宿主 、 服 务 器 和 框架 独立 于 应 用 程 
序 启动 ， 然 后 在 指定 的 点 调用 应 用 程序 。 在 这 种 模式 中 ， 开 发 者 的 代码 实际 上 是 底层 框架 
的 扩展 ， 因 此 ， 应 用 程序 代码 对 请 求 处 理 的 控制 能 力 是 由 框架 决定 的 。 而 且 ， 在 这 种 模式 
中 ， 即 使 应 用 程序 没有 使 用 框架 自身 中 运行 的 某 些 功能 ， 也 要 为 其 付出 性 能 代价 。 


在 基于 OWIN 的 Web 应 用 程序 中 ， 启 动 序列 与 传统 方式 相反 。 宿 主 在 初始 化 环境 字典 并 
选择 服务 器 之 后 ， 立 即 发 现 并 调用 开发 者 的 应 用 程序 代码 ， 以 判断 哪些 组 件 应 该 包含 在 
OWIN 管道 内 。 在 默认 情况 下 ，Katana 宿主 按照 如 下 规则 发 现 开发 者 的 启动 代码 : 














( 按 优先 级 顺序 ) 查找 或 发 现 一 个 启动 类 ; 

如 果 配 置 文件 包含 带 有 key 为 owin:AppStartup 的 appSetting， 则 使 用 此 设置 值 ; 
如 果 存 在 程序 集 属 性 0winstartupAttribute， 则 使 用 属性 中 定义 的 类 型 ， 
扫描 所 有 程序 集 ， 寻 找 一 个 名 为 Startup 的 类 型 ， 

如 果 找 到 启动 类 ， 找 到 其 中 与 签名 void Configuration(IAppBuilder app) 匹配 的 方法 ， 
调用 这 个 配置 方法 。 

















按照 这 个 默认 的 发 现 逻 辑 ， 我 们 只 需要 给 项 目 添加 一 个 启动 类 ， 就 可 以 让 Katana 宿主 的 加 
载 程序 发 现 并 运行 这 个 类 的 配置 方法 : 


public class Startup 


{ 
public void Configuration(IAppBuilder app) 


{ 
app.Use(typeof (MyMiddleware) ); 
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在 这 个 启动 类 的 配置 方法 中 ， 我 们 可 以 调用 传 入 的 TAppButlder 对 象 的 Use 方法 ， 构 造 
OWIN 管道 。Use 是 一 个 泛 型 方法 ， 可 以 将 任何 实现 了 应 用 程序 委托 的 组 件 配置 在 管道 中 。 
此 外 ， 很 多 中 间 件 组 件 和 框架 还 提供 了 自己 的 扩展 方法 ， 以 简化 管道 配置 。 例 如 : ASP. 
NET Web API 提供 UseWebApi 扩展 方法 ， 可 以 使 用 如 下 代码 进行 配置 : 











var config = new HttpConfiguration(); 


// 配置 Web API 
Th was 


app.UseWebApi(config) ; 
但 是 ， 当 你 使 用 Web API 的 配置 扩展 方法 时 ， 实 际 发 生 了 什么 ?通过 更 深入 地 了 解 Web 


API 配置 方法 和 Web API 中 间 件 组 件 ， 你 可 以 更 好 地 理解 OWIN 管道 和 Katana 的 实现 ， 
以 及 Web API 的 宿主 适 配 程序 设计 的 独立 性 。 





11.3.3 Web API 配 置 


UseWebApi 方法 位 于 System.Neb.Http.0win 程序 集 的 WebApiAppBuilderExtensions 类 中 。 
当 从 用 户 的 启动 类 中 调用 UseWebApi 方法 时 ， 这 个 方法 构建 HttpMessageHanLderAdapter 
类 ( 即 OWIN 的 Web API 中 间 件 组 件 ) 的 一 个 实例 ， 并 使 用 泛 型 方法 Use， 将 其 添加 到 
TAppBuilder 实例 中 。 从 UseWebApi 方法 的 代码 中 ， 我 们 可 以 了 解 Katana 基础 结构 如 何 将 
中 间 件 绑 定 在 一 起 ， 形 成 完整 的 管道 : 











public static IAppBuilder UseWebApi( 
this IAppBuilder builder, 
HttpConfiguration configuration) 


IHostBufferPolicySelector bufferPolicySelector = 
configuration. Services .GetHostBufferPolicySelector() 
?? _defaultBufferPolicySelector; 


return builder .Use(typeof(HttpMessageHandlerAdapter), 
new HttpServer(configuration), bufferPolicySelector); 


} 











泛 型 方法 Use 的 第 一 个 参数 是 Web API 中 间 件 的 类 型 ， 甚 后 可 以 有 任意 多 个 附加 人 参数。 在 
添加 Web API 中 间 件 时 ， 代 码 使 用 了 两 个 附加 参数 : 一 个 是 Httpserver 实例 ， 用 传 入 的 
HttpConfiguration 对 象 进行 了 配置 ， 另 一 个 对 象 告 诉 中 间 件 如 何 处 理 请 求 和 响应 流 。 传 
给 Use 方法 的 中 间 件 不 是 实例 ， 而 是 一 个 类 型 ， 因 此 基础 结构 在 创建 中 间 件 实例 时 ， 可 以 
(通过 中 间 件 的 构造 函数 ) 对 其 进行 配置 ， 使 其 带 有 指向 管道 中 下 一 个 中 间 件 对 象 的 引用 。 
我 们 可 以 查看 HttpMessageHandlerAdapter 的 构造 国 数 ， 了 解 具 体 实现 : 构造 函数 的 第 一 个 
参数 是 next 引用 ， 其 后 是 传 给 泛 型 方法 Use 的 附加 参数 。， 




















注 1: 第 12 章 将 详细 介绍 Web API 分 发 逻辑 ， 其 中 包括 HttpServer 和 HttpMessageHanlder。 
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public HttpMessageHandlerAdapter(OwinMiddleware next, 
HttpMessageHandler messageHandler, 
IHostBufferPolicySelector bufferPolicySelector) : base(next) 








泛 型 函数 Use 的 输出 是 修改 后 的 TAppBuilder 对 象 ， 因 此 扩展 方法 UseWebApi 直接 返回 这 个 
对 象 。 通 过 这 种 方式 返回 IAppButLder， 我 们 在 启动 类 中 构建 OWIN 管道 时 ， 语 法 可 以 更 
为 通顺 。 











11.3.4 Web API 中 间 件 


Web API 一 旦 加 入 OWIN 管道 ，OWIN 服务 器 就 可 以 调用 中 间 件 的 应 用 程序 委托 ， 处 理 
HTTP 请 求 。 让 我 们 回忆 一 下 OWIN 应 用 程序 委托 的 签名 : 




















Func<IDictionary<string, object>, Task> 


Web API 的 HttpMessageHandlerAdapter 类 的 基 类 OwinMiddleware (位 于 Microsoft.Owin 
NuGet 软件 包 中 ) 直接 提供 这 一 函数 。 基 类 OwinMiddleware 为 服务 器 提供 了 应 用 程序 委托 
国 数 ， 并 为 其 派生 类 提供 了 一 个 更 简单 的 API: 























public async override Task Invoke(IOwinContext context) 





其 中 的 上 下 文 对 象 提 供 一 个 类 型 更 强 的 对 象 模式 ， 用 于 访问 环境 字典 成 员 ， 例 如 : HTTP 
请 求 和 响应 对 象 。 表 11-2 概括 了 IOwinContext 目前 提供 的 访问 方法 列表 。 





表 11-2: IOwtinContext 的 属性 访问 方法 





请 求 对 当前 请 求 的 封装 方法 
响应 对 当前 响应 的 封装 方法 
环境 封装 的 OWIN 环境 字典 
认证 (NET 4.5 及 更 高 版 本 ) ”访问 当前 请 求 可 以 使 用 的 认证 中 间 件 功能 








上 下 文 对 象 中 的 每 个 属性 提供 对 环境 字典 中 不 同 成 员 的 强 类 型 访问 。 要 了 解 每 个 不 同 的 封 
装 类 型 ， 请 参考 Microsoft.Owin 的 源 代码 (http://katanaproject.codeplex.com/SourceControl/ 
latest#README ) 。 


在 流 经 OWIN 管道 时 ， 如 果 请 求 遇 到 了 HttpMessageHandlerAdapter 的 Invoke 方法 ， 会 按 
照 图 11-14 所 示 的 数据 流程 进行 处 理 。 


作为 OWIN 管道 和 Web API 编程 模型 之 间 的 桥梁 ，HttpMessageHandlerAdapter 执行 的 一 
个 动作 是 将 在 OWIN 环境 字段 中 找到 的 对 象 转换 为 Web API 使 用 的 基础 类 型 。 当 然 ， 这 
些 基础 类 型 就 是 HttpRequestMessage 和 HttpResponseMessage。 在 将 HTTP 请 求 发 送 给 Web 
API 进行 处 理 之 前 ， 中 间 件 还 会 从 环境 字典 中 ，( 通 过 IOwinContext.Request.User) 取得 
用 户 对 象 (如 果 存 在 的 话 ) ， 并 将 这 个 对 象 赋 给 活动 线程 的 CurrentPrincipal 属性 。 






































图 11-14: Web API 中 间 件 数据 流 


如 果 中 间 件 得 到 了 请 求 的 HttpRequestMessage 表示 ， 就 可 以 采取 与 之 前 描述 的 Web API 
托管 基础 结构 组 件 类 似 的 方式 ， 调 用 Web API。 第 12 章 将 介绍 ，Httpserver 类 型 派生 自 
HttpMessageHandler， 是 Web API 消息 处 理 程序 管道 的 入 口 (开发 者 也 可 以 通过 扩展 方 
法 重 载 ， 指 定 另 一 个 称 作 分 发 程序 的 HttpMessageHandler 对 象 ， 作 为 消息 处 理 程序 管道 
的 最 后 一 个 节点 )。HttpMessageHandler 不 能 直接 进行 调用 ， 因 此 中 间 件 将 其 封装 在 一 个 
HttpMessageInvoker 对 象 中 ， 使 用 如 下 代码 调用 : 


response = await _messageInvoker .SendAsync(request, owinRequest.CallCancelled); 


这 个 调用 开始 了 HttpRequestMessage 在 Web API 的 消息 处 理 程序 管道 和 控制 器 管道 中 的 处 
































理 过 程 ， 并 将 指向 结果 HttpResponseMessage 的 引用 保存 在 一 个 本 地 变量 中 。 第 12 章 将 详 
细 讨 论 消息 处 理 程序 和 控制 器 管道 。 























Web API 中 间 件 的 一 个 额外 任务 是 ， 判 断 如 何 处 理 HttpResponseMessage 的 HTTP 状态 码 
404 Not Found。 这 个 任务 非常 重要 ， 因 为 在 OWN 管道 的 环境 中 ，404 状态 码 的 产生 可 能 
有 以 下 两 种 原因 。 


。 请 求 不 匹配 HttpConfiguration 对 象 中 指定 的 任何 HttpRoutes。 在 这 种 情况 下 ， 中 间 件 
应 该 调用 下 一 个 中 间 件 组 件 的 应 用 程序 委托 。 

。 作为 应 用 程序 协议 的 实现 ， 应 用 程序 开发 者 明确 返回 这 个 状态 码 (例如 ， 对 于 请 求 GET 
/api/widgets/123， 小 工具 数据 库 中 无 法 找到 物品 123) 。 在 这 种 情况 下 ， 中 间 件 不 应 该 
调用 组 件 链 中 的 下 一 个 组 件 ， 而 是 应 该 向 客户 端 返 回 状 态 码 为 404 的 响应 。 


























对 于 Web API 中 间 件 而 言 ， 由 Web API 的 路 由 匹配 逻辑 设置 的 404 响应 码 称 为 一 个 “ 软 
404"， 可 以 通过 响应 消息 属性 集中 的 一 个 附加 设置 一 一 HttpPropertyKeys.NoRouteMatched 
存在 与 否 来 判断 。 如 果 不 存 在 这 个 设置 ， 中 间 件 认为 一 个 464 响应 码 是 “ 硬 404”， 会 立刻 向 
客户 端 返回 一 个 状态 码 为 494 的 HTTP 响应 。 





11.3.5 OWIN 生 态 环境 


Katana 组 件 的 内 容 比 本 章 中 讨论 的 要 多 很 多 。 最 新 发 布 的 Katana 组 件 包含 了 认证 组 
件 〈 既 有 社会 开发 ， 也 有 企业 提供 的 中 间 件 )、 诊 断 中 间 件 、HttpLisenter 服务 器 ， 以 
及 OwinHost.exe 宿主 。 第 15 章 将 更 为 详细 地 介绍 基于 OWIN 的 认证 组 件 。 随 着 时 间 推 
移 ，Microsoft 将 会 提供 更 多 兼容 OWIN 的 组 件 ， 逐 步履 盖 System.Web.dll 目前 提供 的 许 
多 常用 功能 。 此 外 ， 由 社区 创建 的 第 三 方 组 件 也 在 持续 增加 ， 目 前 已 经 包含 了 很 多 不 同 的 
HTTP 框架 以 及 中 间 件 组 件 。 在 未 来 几 年 ， 我 们 将 会 看 到 OWIN 组 件 空间 的 急剧 扩展 。 


11.4 内 存 托管 


还 有 一 种 Web API 托管 方式 主要 在 测试 时 使 用 ， 这 种 托管 方式 基于 HttpCLient 实例 和 
HttpServer 实例 的 直接 连接 ， 通 常 称 为 内 存 托管 (in-memory hosting)。 











第 14 章 将 会 介绍 ，HttpClient 实例 可 以 由 构造 函数 中 传 入 的 HttpMessageHandler 进行 配置 。 
客户 端 随后 可 以 使 用 这 个 HttpMessageHandler， 从 HTTP 请 求 异步 获得 HTTP 响应 。 通 常情 
况 下 ， 这 个 HttpMessageHandler 要 么 是 一 个 HttpCLientHandLer， 使 用 底层 网 络 基 础 结构 ， 发 
送 和 接收 HTTP 消息 ， 要 么 是 一 个 DelegatingHanlder ， 对 请 求 和 响应 各 自 执行 前 后 处 理 。 


但 是 ，HttpServer 类 也 可 以 对 HttpMessageHandler 进行 扩展 ， 也 就 是 说 ， 在 构造 HttpCLient 
时 ， 你 也 可 以 使 用 HttpServer。 这 使 得 客户 端 和 服务 器 可 以 直接 进行 内 存 通信 ， 无 需 任 何 
网 络 栈 的 开销 ， 这 个 功能 在 测试 中 非常 有 用 。 示 例 11-5 展示 了 如 何 使 用 内 存 托管 功能 。 
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示例 11-5: 内 存 托管 
var config = new HttpConfiguration(); 
config.Routes.MapHttpRoute("default", "{controller}/{id}", 
new { id = RouteParameter.Optional }); 

var server = new HttpServer(config); 

var client = new HttpClient(server); 

var c = client.GetAsync("http://can.be.anything/resource").Result 

.Content.ReadAsStringAsync().Result; 





示例 11-5 中 的 主机 名 can.be.anything 一 点 也 没有 和 夸张， 因为 没有 使 用 网 络 层 ， 系 统 会 忽 
略 URI 的 主机 名 部 分 ， 所 以 主机 名 可 以 随便 写 。 



































HttpServer 和 HttpClient 是 对 称 的 ， 一 个 是 消息 处 理 程序 ， 另 一 个 接收 请 息 处 理 程序 ， 


此 客户 端 和 服务 器 可 以 建立 直接 联系 ， 如 图 11-15 所 示 。 








HttpClient 





具体 控制 器 
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控制 器 分 发 程序 
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消息 处 理 程序 
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HttpServer 











11-15: 内 存 托管 示意 图 
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11.5 Azure Service Bus Host 


在 本 章 最 后 ， 我 们 要 举例 介绍 开发 定制 托管 适 配 层 。 我 们 将 以 Windows Azure Service Bus 
为 例 ， 这 是 一 个 云 托管 的 基础 结构 ， 提 供 消 息 中 转 (brokered) 和 中 继 (relayed) 功能 。 消 
息 中 转机 制 有 : FAX] (queue) 和 主题 (topic)， 既 使 发 送 者 和 接受 者 在 时 间 上 去 耦 ， 又 提 
供 消 息 广 播 。 消 息 中 继 可 以 将 托管 在 内 部 网 络 中 的 API 向 外 部 公开 ， 是 这 一 节 讨 论 的 重点 。 


























在 图 11-16 F, 一 个 API ( 即 : 一 组 资源 ) 托管 在 一 台 具 有 如 下 特征 的 机 器 上 : 


。 位 于 内 部 网 络 中 ， 设 有 外 部 卫 或 外 部 DNS 4; 
。 通过 NAT (Network Address Translation, 网 络 地 址 转换 ) 和 防火 墙 系统 , 与 








>H 





特 网 隔离 。 











Windows Azure 












外 部 下 Service Bus 
外 部 DNS 名 中 继 





API 客 户 端 


11-16: Service Bus 使 用 场景 






NAT 防 火 墙 内 部 IP 
没有 DNS 名 














这 种 设 定 的 一 个 具体 例子 是 ， 提 供 Web API 的 家 居 自 动 化 系统 。 通 常 的 家 庭 因 特 网 连接 
(例如 ， 通 过 DSL 连接 ) 具有 图 11-16 中 描述 的 特征 一 一 即 : 没有 外 部 IP 地 址 或 DNS 名 ， 
也 没有 NAT 和 防火 墙 阻 断 进 入 的 连接 。 但 是 ， 如 果 位 于 因特网 上 的 外 部 客户 端 可 以 使 用 
这 个 API， 这 个 功能 将 非常 有 用 。 例 如 : 设想 一 下 ， 我 们 可 以 据 此 使 用 智能 手机 ， 远 程控 
制 房间 温度 ， 或 者 查看 监控 画面 。 
































如 图 11-16 所 示 ，Service Bus 中 继 功 能 作为 客户 但 和 API 宿主 之 间 的 中 介 ， 解 决 了 这 些 连 
接 问 题 。 


。 首先 ,宿主 与 Service Bus 中 继 建立 一 个 向 外 的 连接 。 因 为 这 个 连接 是 向 外 的 ,不 是 向 内 的 ， 
所 以 在 内 部 不 需要 公共 IP， 网 络 地 址 的 转换 由 NAT 完成 。 
。 建立 连接 之 后 ，Service Bus 中 继 使 用 自己 的 命名 空间 中 的 一 个 域名 (例如: webapibook. 


servicebus.windows.net), 创建 和 提供 一 个 外 部 端点 。 
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。 发 送 到 这 个 外 部 端点 的 每 个 请 求 , 都 会 通过 之 前 建立 的 向 外 连接 , 接着 发 送 到 API 宿主 。 
由 API 宿主 产生 的 响应 也 通过 这 个 向 外 连接 返回 ， 并 由 Service Bus 中 继 发 送 给 客户 端 。 


Azure Service Bus 支持 多 个 租户 ， 每 个 租户 拥有 一 个 DNS 名 ,格式 为 {tenant-namespace}. 
servicebus.windows.net。 例 如 : 这 一 节 的 示例 中 DNS 名 为 webapibook.servicebus. 
windows .net。 当 宿主 与 Service Bus 建立 连接 ， 告 诉 中 继 服务 开始 监听 请 求 时 ， 宿 主 必须 
进行 认证 一 一 也 就 是 说 ， 要 证 明 自 己 可 以 使 用 这 个 租户 的 名 字 。 而 且 ， 宿 主 必须 定义 一 个 
路 径 前 级 ， 用 于 与 租户 的 DNS 结合 ， 形 成 基地 址 。 只 有 带 有 这 个 前 绥 的 请 求 ， 中 继 服务 
才 会 将 其 转发 给 宿主 。 














Azure Service Bus 提供 一 个 SDK (Software Development Kit， 软 件 开发 工具 包 )， 可 以 与 
WCE 编程 模型 集成 ， 为 使 用 Service Bus 中 继 的 宿主 服务 提供 特殊 的 绑 定 。 遗 憾 的 是 ， 在 
这 本 书 编写 时 ， 这 个 工具 包 还 不 支持 ASP.NET Web API。 但 是 ， 基 于 Web API 的 托管 独 
立功 能 ， 参 考 基 于 WCF 的 自 托 管 方式 ， 我 们 可 以 构建 定制 的 HttpserviceBusServer 类 ， 
使 用 Service Bus 中 继 服务 来 进行 ASP.NET Web API 托管 。 








图 11-17 展示 了 HttpServiceBusServer 托管 服务 器 以 及 相关 的 类 。 
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图 11-17: HttpServiceBusServer 及 其 相关 类 


这 个 新 的 服务 器 使 用 HttpServiceBusConfiguration 类 (派生 自 基 类 HttpConfiguration) 
的 一 个 实例 进行 配置 ， 并 专门 为 这 种 托管 情况 添加 了 如 下 属性 : 





。 外 部 的 Service Bus 中 继 地 址 (例如 : https://tenantnamespace.servicebus.windows. 
net/some/path) ; 








e 与 Service Bus 中 继 建 立 向 外 连接 所 需 的 身份 赁 





HttpServiceBusServer 使 用 了 派生 自 基 类 HttpConfiguration 的 专门 配置 类 ， 这 种 设计 与 自 
托管 方式 (参见 图 11-8) 类 似 。HttpServiceBusServer 在 内 部 创建 一 个 WCE WebServiceHost, 
OS WebHttpRelayBinding 配置 的 端点 。WebHttpRelayBinding 是 Service Bus SDK 提 

供 的 新 的 绑 定 类 ， 与 WCF 本 地 的 WebHttpBinding 类 似 ， 主 要 的 不 同 之 处 在 于 : 服务 是 通 
过 Service Bus 中 继 远 程 提供 的 ， 而 不 是 在 本 地 的 托管 机 器 上 。 通 过 端点 接收 到 所 有 请 求 都 
由 DispatcherService 类 的 一 个 实例 进行 处 理 。 








[ServiceContract] 
[ServiceBehavior(InstanceContextMode = InstanceContextMode. Single, 
ConcurrencyMode = ConcurrencyMode.Multiple) ] 
internal class DispatcherService 
[WebGet(UriTemplate = "*")] 
[OperationContract(AsyncPattern = true) ] 
public async Task<Message> GetAsync() 


{...} 


[WebInvoke(UriTemplate = "*", Method = "*")] 
[OperationContract(AsyncPattern = true) ] 
public async Task<Message> InvokeAsync(Message msg) 
Fesat 

} 


这 个 泛 型 服务 实现 了 两 个 异步 操作 : Get 和 Invoke, Get 操作 处 理 所 有 GET 方法 的 HTTP 
请 求 。Invoke 操作 处 理 其 他 的 所 有 请 求 (Method = "*")。 请 注重 ， 这 两 个 操作 都 有 
UriTemplate = "“*"， 说 明 都 处 理 任何 路 径 的 请 求 。 


























当 这 两 个 方法 中 的 任何 一 个 收 到 一 个 请 求 时 ， 请 求 消息 的 本 地 表示 会 转换 成 一 个 新 
的 HttpRequestMessage 实例 ， 然 后 这 个 新 实例 会 推送 到 一 个 内 部 的 HttpServer。 这 
个 内 部 HttpServer 在 HttpServiceBusServer 构造 函数 中 创建 ， 由 传 入 的 HttpService 
BusConfiguration 配置 。 可 是 ，HttpServer.SendAsync 是 一 个 受 保护 方法 ， 因 此 不 能 直接 
调用 。 但 是 ，HttpMessageInvoker 可 以 封装 包括 HttpServer 在 内 的 任何 消息 处 理 程序 ， 并 
提供 一 个 公共 的 SendAsync 方法 : 








THE 
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public DispatcherService(HttpServer server, HttpServiceBusConfiguration config) 


{ 
_serverInvoker = new HttpMessageInvoker(server, false); 
_config = config; 


} 


当 HttpServer 生 成 HttpResponseMessage 后 ，DispatcherService 将 HttpResponseMessage 


转换 回 WCF 消息 表示 并 返回 。 


Oo 








HttpServiceBusServer 的 整体 设计 受到 基于 WCF 的 自 托管 适 配 层 的 启发 ， 但 有 两 点 不 同 之 
处 。 第 一 个 ， 也 是 最 重要 的 不 同 之 处 在 于 ，Service Bus 宿主 位 于 WCF 服务 模型 之 上 ， 而 





自 托管 直接 使 用 了 WCF 信道 。 这 种 设计 虽然 会 带 来 额外 的 开销 ， 但 是 实现 更 为 简单 ， 
而 得 到 采纳 。 





第 二 个 不 同 之 处 是 ，HttpServiceBusServer 没有 直接 继承 HttpServer 类 。HttpService 
BusServer 没有 像 HttpSelfHostServer 一 样 使 用 基于 类 继承 的 设计 ， 而 是 使 用 组 合 方 式 : 
在 内 部 创建 和 使 用 一 个 HttpServer 实例 。 








HttpServiceBusServer 的 实现 可 以 在 源 代码 (https://github.com/pmhsfelix/WebApi.Explorations. 
ServiceBusRelayHost) 中 找到 。 源 代码 库 还 提供 一 个 示例 ， 展 示 使 用 这 个 新 的 Web API 托 
管 方式 的 简单 性 。ServiceBusRelayHost.Demo.Screen 项 目 定义 了 一 个 Service Bus 托管 的 服 
务 ， 其 中 只 有 一 个 资源 。 





public class ScreenController : ApiController 


{ 
public HttpResponseMessage Get() 
{ 
var content = new StreamContent(ScreenCapturer.GetEncodedByteStream()); 
content.Headers.ContentType = new MediaTypeHeaderValue( "image/jpeg" ); 
return new HttpResponseMessage( ) 
{ 
Content = content 
J; 
} 
} 


代码 中 用 到 的 ScreenCapturer 是 一 个 辅助 类 ， 用 于 屏幕 截图 。 这 个 资源 控制 器 的 托管 也 非 
常 简 单 。 


var config = new HttpServiceBusConfiguration( 
ServiceBusCredentials.ServiceBusAddress) 


{ 

IssuerName = "owner", 

IssuerSecret = ServiceBusCredentials.Secret 
J; 
config .Routes .MapHttpRoute( 


"default", 

"{controller}/{id}", 

new { id = RouteParameter.Optional }); 
var server = new HttpServiceBusServer (config) ; 
server .OpenAsync().Wait(); 


首先 ， 代 码 使 用 Service Bus 地 址 、 访 问 凭据 (IssueSecret) 和 访问 用 户 名 (owner) 初始 
化 一 个 HttpServiceBusConfiguration 实例 ， 然 后 ， 和 其 他 的 托管 方式 一 样 ， 将 路 由 添加 到 
Routes 属性 ， 最 后 ， 使 用 这 个 配置 实例 ， 配 置 一 个 HttpServiceBusServer， 并 明确 启动 服 
务 器 。 





图 11-18 展示 了 通过 一 个 简单 的 旧 浏 览 器 ， 访 问 这 个 通过 Azure Service Bus 托管 的 屏幕 资 








托管 | 255 


源 的 结果 。 请 注意 ， 浏 览 器 的 地 址 栏 中 使 用 了 一 个 外 部 DNS 名 。 





@ screen (JPEG Image, 1680 x 1050 pixels) - Scaled (44%) - Mozilla Firefox -5 Ea 
File Edit View History Bookmarks Tools Help 


screen (JPEG Image, 1680 x 1050 pixels) ...| + 





us.windows.net/webapi/screer 














11-18: 访问 通过 Service Bus 托管 的 屏幕 资源 


11.6 小结 


本 章 主 要 关注 Web API 与 外 部 的 托管 基础 结构 进行 交互 的 方式 ， 不 仅 描述 了 已 有 的 托管 
适 配 层 (Web 托管 和 自 托管 )， 而 且 讨 论 了 基于 OWN 规范 的 新 托管 方式 和 Katana 项 目 ， 
最 后 还 介绍 了 内 存 托管 和 定制 托管 适 配 层 的 一 个 例子 。 在 随后 的 章 闻 中， 我 们 将 转 而 关注 
ASP.NET Web API 中 更 高 的 层次 ， 特 别 是 路 由 和 控制 器 。 
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控制 器 和 路 由 





知道 家 里 的 水 管 如 何 工作 ， 大 部 分 时 候 都 没什么 用 处 





但 是 当 你 需要 这 些 知识 时 ， 
一 无 所 知 的 后 果 就 会 很 严重 。 











虽然 ASPNET Web API 提供 了 许多 有 用 的 高 层 功能 ， 从 序列 化 和 模型 绑 定 到 OData 风格 
查询 支持 ， 但 是 和 所 有 的 Web API 一 样 ，ASP.NET Web API 的 核心 任务 是 处 理 HTTP 请 
求 并 提供 适当 的 响应 。 因 此 ， 对 于 一 个 HTTP 请 求 如 何 从 客户 端 开始 ， 流 经 ASP.NET Web 
API 基础 结构 和 编程 模型 的 各 个 元 素 ， 最 终 产生 一 个 可 以 发 送 回 客户 端的 HITP 响应 ， 我 
们 需要 理解 这 一 过 程 的 核心 机 制 ， 这 一 点 至 关 重 要 。 





























本 章 关注 前 面 提 到 的 消息 流 ， 讨 论 其 基本 机 制 ， 以 及 支持 请 求 处 理 和 响应 生成 的 编程 模 
型 。 此 外 ， 本 章 还 将 介绍 关键 类 型 和 插入 点 (insertion point)。 使 用 这 些 插 入 点 , 我 们 可 以 
扩展 ASP.NET Web API 框架 ,支持 定制 的 消息 流 和 处 理 方案 。 


12.1 HTTP 消 息 流 概览 


消息 流 经 ASP.NET Web API 的 确切 过 程 ， 会 随 着 托管 方式 的 不 同 而 略 有 变化 ， 托 管 在 第 10 章 
中 进行 了 详细 的 介绍 。 但 是 ， 参 与 HITP 消息 流 的 框架 组 件 大 致 可 分 为 两 类 (参见 图 12-1) : 

















。 依靠 HTTP 消息 获得 上 下 文 的 组 件 ， 
。 依靠 高 层 编程 模型 狭 得 上 下 文 的 组 件 。 





第 一 类 组 件 只 依靠 来 自 底 层 “ 消 息 处 理 程序 ”管道 的 核心 HTTP 消息 上 下 文 。 这 些 组 件 从 
托管 抽象 层 获 得 一 个 HttpRequestMessage 对 象 ， 并 最 终 负 责 返 回 一 个 HttpResponseMessage 


WR. 
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12-1: 消息 处 理 程序 和 控制 器 管道 


依赖 高 层 编程 模型 的 组 件 则 不 同 ， 这 些 组 件 可 以 访问 并 使 用 编程 框架 抽象 层 ， 例 如 : 控制 
器 和 操作 方法 ， 以 及 映射 到 HTTP 请 求 不 同 元 素 的 参数 。 








如 前 所 述 ， 像 选择 URL 路 由 这 样 的 低层 机 制 ， 会 随 着 托管 方式 的 不 同 而 变化 。 例 如 ， 
如 果 Web API 作为 托管 在 HS 上 的 MVC 应 用 程序 的 一 部 分 进行 托管 ， 那 么 HITP 消 
息 会 流 经 ASP.NET 提供 的 核心 路 由 基础 结构 。 而 自 托 管 Web API 时， 消息 会 流 经 以 
HttpListener 对 象 为 核心 构建 的 WCF 信道 栈 。 无 论 选 择 何 种 托管 方式 ， 一 个 请 求 最 终 都 
会 转换 成 一 个 HttpRequestMessage 实例 ， 传 给 一 个 HttpServer 实例 。 


12.2 ”消息 处 理 程序 管道 


对 于 宿主 相关 的 组 件 ，Httpserver 是 消息 处 理 程序 管道 的 入 口 。Httpserver 调用 
HttpClientFactory 的 CreatePipeline 方法 ， 使 用 全 局 和 路 由 配置 数据 中 提供 的 处 理 程序 ， 
初始 化 管道 。 其 代码 如 示例 12-1 所 示 。 


示例 12-1: 初始 化 消息 处 理 程 序 管道 
protected virtual void Initialize() 


{ 





// 进行 配置 的 最 后 初始 化 
// 从 这 里 开始 ， 系 统 认为 配置 不 可 变 


_configuration.Initializer(_configuration); 
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// 创建 管道 
InnerHandler = HttpClientFactory.CreatePipeline(_dispatcher, 
_configuration.MessageHandlers); 


} 


最 后 ， 为 HttpServer 自己 派生 于 DelegatingHanlder 类 ，HttpServer 成 为 了 消息 处 理 
程序 管道 中 的 第 一 个 处 理 程序 。 整 个 管道 首先 是 Httpserver 以 及 其 后 的 任意 多 个 定制 的 
DelegatingHanlder 对 象 组 成 ， 这 些 定制 对 象 注册 在 HttpConfiguration 中 ; 接 下 来 是 另 
外 一 个 特殊 的 处 理 程序 HttpRoutingDispatcher; 管道 的 最 后 ， 要 么 是 一 个 在 路 由 注册 时 
提供 的 路 由 相关 的 定制 消息 处 理 程序 (或 者 是 由 HttpClientFactory.CreatePipepline 构 
建 的 另 一 个 消息 处 理 器 管道 )， 要 么 是 默认 的 HttpControllerDispatcher 消息 处 理 程序 。 
HttpControllerDispatcher 选择 和 创建 一 个 控制 器 实例 ， 并 将 消息 分 发 到 这 个 实例 。 
12-2 展示 了 整个 管道 的 组 成 。 






































12-2; 消息 处 理 程序 管道 


HttpServer 将 HttpClientFactory.CreatePipeline 返回 的 值 赋 给 自己 的 InnerHandler 属 
性 ， 从 而 成 为 管道 的 第 一 个 节点 。 因 此 ，Httpserver 可 以 调用 基 类 的 SendAsync 方法 ， 将 
控制 权 移交 给 管道 中 的 下 一 个 处 理 程序 。 管 道中 所 有 的 消息 处 理 程序 都 使 用 这 种 方式 移交 
控制 权 。 





























return base.SendAsync(request, cancellationToken) 


基 类 DelegatingHanlder 直接 调用 对 象 的 InnerHandler 的 SendAsync 方法 。 对 象 的 内 部 处 
理 程序 在 自己 的 SendAsync 方法 中 处 理 消息 ， 然 后 重复 这 一 过 程 ， 调 用 自己 的 内 部 处 理 程 
FREY SendAsync 方法 。 这 个 过 程 一 直 持 续 到 最 后 一 个 处 理 程序 一 一 对 于 典型 的 ASP.NET 
Web API， 最 后 一 个 就 是 将 请 求 分 发 到 控制 器 实例 的 处 理 程序 。 这 种 风格 的 管道 (如 图 
12-3 Bras) 有 了 时 称 作 “俄罗斯 套 娃 ”， 因 为 处 理 程序 一 个 套 着 一 个 ， 外 部 处 理 程序 直接 调 
用 其 内 部 的 处 理 程序 ， 使 得 请 求 数据 从 最 外 层 的 处 理 程 序 一 直流 向 最 内 层 的 处 理 程序 ( 然 
后 响应 数据 反 向 流出 )。) 






















































































注 1: 有 一 种 风格 是 ， 管 道 在 组 件 之 外 ， 管 道 调用 一 个 组 件 ， 获 得 响应 ， 然 后 调用 下 一 个 组 件 ， 以 此 类 推 ， 
使 得 数据 在 管道 中 流动 。 这 种 风格 可 以 与 “俄罗斯 套 娃 ” 风 格 进行 对 比 。 
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HttpServer 
InnerHandler = CustomDelegatingHndler1 


CustomDelegatingHndlr1 
InnerHandler = CustomDelegatingHndler2 


CustomDelegatingHndlr2 


InnerHandler = Dispatcher 














12-3: 消息 处 理 程序 的 “俄罗斯 套 娃 ”模型 


请 记 住 : 这 整个 数据 流 都 是 异步 的 ， 因 此 从 SendAsync 返回 的 值 是 Task。 实 际 上 ，Send 
Async 的 完整 签名 是 这 样 的 : 











Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, 
CancelLlationToken cancellationToken) 


你 可 能 需要 一 段 时 间 ， 才 能 逐步 适应 基于 任务 的 异步 管道 的 使 用 ， 第 10 章 详细 介绍 了 相 
关 的 内 容 。 但 是 ， 创 建 基于 任务 的 消息 处 理 程 序 有 如 下 一 些 基本 规则 。 


。 要 将 控制 权 传 递 给 管道 中 的 下 一 个 ， 或 内 部 的 处 理 程序 ， 你 可 以 返回 调用 基 类 
SendAsync 方法 的 返回 值 。 

。 要 终止 进一步 的 消息 处 理 ， 返 回 一 个 响应 (也 称 为 “短路 ”请 求 处 理 )， 你 可 以 返 
个 新 的 Task<HttpResponseMessage>。 

。 要 在 HTTP 响应 从 最 内 部 处 理 程序 流 回 最 外 部 处 理 程序 时 进行 处 理 ， 你 可 以 在 返回 的 任 
务 上 附加 一 个 延续 (continuation, FA ContinueWith 方法 实现 )。 这 个 延续 应 该 只 有 一 个 
参数 , 即 需 要 延续 的 任务 , 并 应 该 返回 一 个 HttpResponseMessage 对 象 。 在 .NET 框架 4.5 
及 更 高 版 本 中 ， 你 可 以 使 用 async 和 await 关键 字 ， 简 化 异步 代码 的 实现 。 




















el 
| 





























请 参考 示例 12-2 中 的 消息 处 理 程序 ， 这 个 处 理 程序 查看 一 个 HITP GET 请 求 ， 判 断 这 个 请 求 
是 否 为 一 个 条 件 GET〈 即 : 包含 一 个 if-non-match 标 头 的 请 求 )。 如 果 这 个 请 求 是 条 件 请 求 ， 
并 且 本 地 缓存 中 没有 这 个 请 求 的 实体 标签 (ETag)， 处 理 程序 就 认为 底层 的 资源 状态 值 发 生 了 
改变 。 因 此 ， 处 理 程序 让 这 个 请 求 继 续 流 经 管道 ， 通 过 调用 base. SendAsync 并 返回 其 结果 ， 
将 请 求 传递 给 适当 的 处 理 程序 。 这 样 可 以 保证 这 个 GET 请 求 的 响应 包含 资源 的 最 新 表示 。 
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示例 12-2: 处 理 带 有 ETag 的 条 件 GET 请 求 的 消息 处 理 程 序 
protected override Task<HttpResponseMessage> SendAsync( 


HttpRequestMessage request, 
CancellationToken cancellationToken) 


if (request.Method == HttpMethod.Get && 
request.Headers.IfNoneMatch.Count > 0 && 
(!IfNoneMatchContainsStoredEtagValue( request) )) 


return base.SendAsync(request, cancellationToken).ContinueWith(task => { 
var resp = task.Result; 
resp.Headers.ETag = new EntityTagHeaderVaLue( 
_eTagStore.Fetch(request.RequestUri)); 
return resp; 


p; 


// 默认 情况 下 ， 让 请 求 继 续 流 经 消息 处 理 程序 管道 
return base.SendAsync(request, cancellationToken); 





} 





这 个 处 理 程序 也 可 以 给 返回 的 任务 添加 一 个 延续 ， 以 便 给 啊 应 消息 创建 和 设置 一 个 新 的 
ETag 值 。 此 后 对 这 个 资源 的 请 求 就 可 以 传递 这 个 新 的 ETag 值 ， 进 行 验证 。 














使 用 HttpMessageInvoker 调用 一 个 消息 处 理 程序 


如 果 你 使 用 过 消息 处 理 程序 ， 可 能 已 经 知道 SendAsync 方法 是 一 个 受 保护 的 内 部 方法 ， 
因此 可 能 会 问 ，HttpServer 本 身 是 从 DelegationHandler 派生 的 ， 外 部 类 型 (也 就 是 组 
成 底层 托管 基础 结构 的 类 型 ) 怎么 能 对 HttpServer 的 SendAsync 进行 调用 呢 ? 


为 了 调用 SendAsync 方法 ， 类 可 以 使 用 System.Net.Http 程序 集 提供 的 HttpMessageInvoker , 
Sytem.Net.Http 程序 集 还 提供 DelegatingHandler 的 基 类 HttpMessageHandler 。 


为 HttpMessageInvoker 和 HttpMessageHandler 位 于 同一 个 程序 集中 ， 而 且 SendAsync 
是 一 个 受 保 护 的 内 部 方法 ， 因 此 SendAsync 可 以 从 HttpMessageHandler 的 派生 类 或 者 
同一 个 程序 集中 的 类 型 中 调用 ， 位 于 同一 程序 集中 的 HttpMessageInvoker 就 可 以 调用 
SendAsync。 因 此 ， 要 执行 一 个 消息 处 理 程序 ， 你 可 以 构建 一 个 新 的 HttpMessageInvoker， 
用 如 下 代码 调用 其 公开 的 SendAsync 方法 : 


var handler = new MyHandler(); 
var invoker = new HttpMessageInvoker (handler); 


Task responseTask = invoker.SendAsync(request, cancellationToken) ; 
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12.2.1 分 发 程序 

消息 处 理 程序 管道 的 最 后 一 个 阶段 是 分 发 。 在 ASP.NET Web API 的 较 早 版 本 中 ,分 发 阶 
段 是 预先 定义 的 ， 从 路 由 数据 提供 的 信息 中 选择 一 个 控制 器 ， 获 得 该 控制 器 的 实例 ， 然 
把 HTTP 消息 和 上 下 文 信息 传 给 控制 器 ， 由 控制 器 的 执 wae 了 处理。 你 还 是 可 以 添加 
一 个 定制 的 消息 处 理 器 ,返回 一 个 新 的 Task 对 象 ， 从 而 绕 过 控制 器 编程 模型 。 但 是 ， 这 个 
消息 处 理 器 必须 添加 到 全 局 的 HttpConfiguration 对 象 中 ， 也 就 是 说 ， 这 个 处 理 器 需要 处 
理发 送 到 这 个 Web API 的 每 一 个 HTTP 请 求 。 






































为 了 使 消息 处 理 程序 可 以 按 不 同 路 由 进行 配置 ， 也 为 了 支持 使 用 非 IHttpController 的 
高 层 抽象 的 不 同 的 Web API HEE, ASP.NET Web API 团队 给 分 发 过 程 添加 了 一 个 间 
接 层 。HttpServer 使 用 HttpRoutingDispatcher 的 一 个 实例 作为 消息 处 理 程序 管道 的 最 
后 一 个 布点 。 从 下 面 的 产品 源 代码 节选 ， 我 们 可 以 看 到 ，HttpRoutingDispatcher 负责 
调用 由 路 由 提供 的 一 个 定制 的 消息 处 理 程 序 ， 或 者 默认 的 HttpControllerDispatcher。 
HttpControllerDispatcher 派生 自 HttpMessageHandler, HttpMessageHandler 无 法 直接 调用 ， 
因此 HttpRoutingDispatcher 将 分 发 程序 实例 封装 在 一 个 HttpMessageInvoker 对 象 中 执行 


























var invoker = (routeData.Route == null || routeData.Route.Handler == null) ? 
_defaultInvoker : new HttpMessageInvoker(routeData.Route.Handler, 
disposeHandler: false); 

return invoker.SendAsync(request, cancellationToken) ; 





路 由 相关 的 消息 处 理 程序 作为 路 由 配置 自身 的 一 部 分 进行 声明 。 例 如 ， 请 看 下 面 的 路 由 注 
册 代 码 : 











public static void Register(HttpConfiguration config) 
{ 
config.Routes.MapHttpRoute("customHandler", "custom/{controller}/{id}", 
defaults: new {id = RouteParameter.Optional}, 
constraints: null, 
handler: HttpClientFactory.CreatePipeline( 
new HttpControllerDispatcher (config), 
new[] {new MyHandler()}) 


} 


custonHandler 路 由 除了 包含 标准 的 路 由 配置 和 注册 代码 ， 还 提供 一 个 定制 的 消息 处 理 程序 ， 
作为 MapHttpRoute 的 最 后 一 个 参数 。 但 是 ， 实 际 上 ， 这 段 代 码 不 仅 注册 了 定制 消息 处 理 程 
序 MyHandler 的 一 个 实例 ， 还 使 用 帮助 方法 HttpClientFactory.CreatePipeline， 用 默认 的 
HttpControllerDispatcher 消息 处 理 器 构建 MyHandler。 如 果 你 要 插入 路 由 相关 的 消息 处 理 
程序 ， 一 定 要 记 住 这 一 点 : 如 果 将 一 个 定制 消息 处 理 程序 提供 给 HttpRoutingDispatcher， 

这 个 消息 处 理 程序 就 要 负责 处 理 将 来 所 有 的 HTTP 消息 。CreatePipeline 的 第 一 个 参数 
是 所 需 的 “最 终 目 标 ” 消 息 处 理 程序 ， 后 面 的 参数 古 组 成 管道 的 其 他 所 有 消息 处 理 程 
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FF. CreatePipeline 方法 会 为 每 个 消息 处 理 程序 设置 InnerHandter 属性 ， 将 其 连 成 一 串 ， 
并 返回 串 中 的 第 一 个 消息 处 理 程序 。 在 示例 中 ， 这 个 “ 串 ” 包 含 MyHandter 以 及 后 面 的 
HttpControllerDispatcher。 请 记 住 ,对 于 这 样 创建 的 消息 处 理 程序 管道 ， 除 了 最 内 部 的 
处 理 程序 之 外 ， 其 他 所 有 消息 处 理 程序 都 必须 派生 自 DelegatingHanlder， 不 能 直接 继承 
HttpMessageHandler, ， 因 为 DelegatingHandler 才 支 持 通过 InnerHandler 属性 进行 连接 。 



























































12.2.2 HttpControllerDispatcher 


在 默认 情况 下 ， 消 息 处 理 程 序 管道 的 最 后 一 环 是 HttpControllerDispatcher。 这 个 处 理 程 
序 将 消息 处 理 程序 管道 和 上 层 的 编程 模型 元 素 控 制 器 和 操作 (我 们 称 之 为 控制 器 管道 ) BB 
定 在 一 起 。HttpControLLerDispatcher 执行 三 项 任务 : 



































。 使 用 一 个 实现 IHttpControllerSelector 接口 的 对 和 象 ， 选 择 一 个 控制 器 ， 

。 使 用 一 个 实现 IHttpControllerActivator 接口 的 对 象 ， 获 得 一 个 控制 器 的 实例 ; 

。 给 控制 器 实例 传人 一 个 控制 右上 下 文 对 象 ， 其 中 包含 当前 配置 、 路 由 和 请 求 上 下 文 ， 执 
行 控 制 器 实例 。 





为 了 完成 这 些 任务 ，HttpControllerDispatcher 使 用 了 两 种 值得 注意 的 类 型 ， 即 实现 
IHttpControllerSelector 接口 的 类 型 ， 和 实现 IHttpControLLerActivator 接口 的 类 型 。 





12.2.3 ”控制 器 选择 

正如 其 名 称 所 示 ，IHttpControLLerSetLector 的 作用 是 基于 HTTP 请 求 选 择 适 当 的 控制 器 
ASP.NET Web API 提供 一 个 默认 实现 DefaultHttpControllerSelector, 这 个 类 使 用 如 下 算 
法 进行 控制 器 选择 。 

。 判断 控制 器 是 否 可 以 从 路 由 数据 直接 发 现 。 使 用 基于 属性 的 路 由 时 ， 这 一 条 件 为 真 。 

。 检查 控制 器 名 是 否 有 效 。 如 果 控 制 器 名 缺失 或 者 为 空 字符 串 , 就 抛 出 一 个 404 响应 异常 。 
。 使 用 控制 器 名 ， 在 控制 器 信息 缓存 中 寻找 匹配 的 HttpControllerDescriptor 并 返回 。 


控制 器 信息 缓存 是 一 个 字典 ,保存 控制 器 名 ， 以 及 缓存 首次 访问 时 初始 化 的 
HttpControllerDescriptor 对 和 象 。 在 初始 化 过 程 中 ， 控 制 器 信息 缓存 使 用 HttpController 
TypeCache 的 一 个 实例 ， 该 实例 使 用 实现 IHttpControllerTypeResolver 接口 的 一 个 对 象 ， 
遍历 程序 集 和 类 型 ， 构 建 包 含 所 有 有 效 控制 器 类 型 的 列表 。 默 认 情 况 下 ，Web API 使 用 De 
faultHttpControllerTypeResolver, DefaultHttpControllerTypeResolver 认为 符合 如 下 条 件 
的 类 型 为 有 效 的 控制 器 : 
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。 实现 或 继承 一 个 实现 IHttpController 接口 的 类 ， 
。 类 名 以 字符 串 "Controller" 结尾 。 

















控制 器 是 在 DefaultHttpControllerSelector 信息 缓存 首次 访问 时 发 现 的 ， 如 果 没 有 为 指 
定 的 控制 器 名 找到 唯一 一 个 匹配 的 控制 器 ， 就 会 导致 默认 控制 选择 逻辑 的 错误 。 例 如 : 如 
果 没 有 为 指定 的 控制 器 名 找到 一 个 缓存 条 目 ， 框 架 就 会 向 客户 端 返回 一 个 HTTP 响应 404 
Not Found。 另 外 ， 如 果 为 指定 的 控制 妖 名 找到 多 个 条 目 ， 那 么 框架 会 因 模糊 匹配 抛 出 一 个 








InvalidOperationException, 





假设 指定 的 控制 如 名 ， 匹 配 默认 控制 器 选择 程序 的 信息 缓存 中 的 一 个 条 目 ， 探 制 器 选择 程 
序 会 把 相应 的 HttpControllerDescriptor 返回 给 发 起 调用 的 HttpControllerDispatcher。 





这 里 还 有 一 点 要 注意 : 控制 器 描述 符 (controller descriptor) 的 生命 期 和 HttpConfiguration 





对 象 一 样 ， 也 就 是 说 ， 控 制 器 描述 符 的 生命 期 就 是 应 用 程序 的 生命 期 。 
1. 支持 基于 属性 的 路 由 








Web API 2 增加 了 将 路 由 指定 为 属性 的 功能 。 这 些 属性 既 可 应 用 于 控制 器 类 ， 也 可 应 用 于 
操作 方法 。 纯 粹 基于 约定 (convention-based) 的 方法 使 用 路 由 参数 和 命名 约定 ， 进 行 控制 








器 和 操作 的 匹配 ， 基 于 属性 的 声明 式 方法 是 对 基于 约定 方法 的 补充 。 





使 用 基于 属性 的 路 由 ， 在 过 程 上 分 为 两 步 。 第 一 步 是 用 RouteAttribute 修饰 控制 器 和 /或 
操作 ， 提 供 适 当 的 路 由 模板 值 。 第 二 步 是 让 Web API 将 这 些 属 性 值 映射 到 实际 的 路 由 数 


据 ， 供 框架 在 处 理 请 求 时 使 用 。 





例如 ， 请 看 一 个 基本 的 问候 Web API: 
public class GreetingController : ApiController 


// 默认 映射 到 GET /api/greeting 
public string GetGreeting() 
{ 


} 
} 


return "Hello!"; 


使 用 基于 属性 的 路 由 ， 我 们 无 需 修改 全 局 路 由 配置 规则 ， 就 可 以 将 这 个 控制 器 


到 一 个 完全 不 同 的 URL: 


public class GreetingController : ApiController 
{ 
// 映射 到 GET /services/hello 
[Route("services/hello")] 
public string GetGreeting() 
{ 


} 
} 


return "Hello!"; 


和 操作 映射 
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为 了 确保 这 个 基于 属性 的 路 由 正确 添加 到 了 Web API 的 路 由 配置 中 ， 我 们 必须 调用 
HttpConfiguration 的 MapHttpAttributeRoutes 方法 : 


config.MapHttpAttributeRoutes(); 








这 种 方式 在 配置 时 集成 属性 路 由 ， 可 以 减少 对 其 他 框架 组 件 的 修改 。 例 如 ， 因 为 
所 有 解析 和 惯例 基于 属性 的 路 由 值 的 复杂 性 都 在 Route Data 层 进行 处 理 ， 所 以 对 
DefaultHttpControllerSelector 的 影响 仅 限于 如 下 部 分 : 








controllerDescriptor = routeData.GetDirectRouteController(); 
if (controllerDescriptor != null) 


{ 
} 


我 们 从 这 段 代码 可 以 看 出 ， 如 果 通 过 基于 属性 的 路 由 匹配 可 以 明确 得 到 一 个 控制 器 和 /或 
操作 ， 那 么 系统 就 会 立即 选择 和 返回 相关 的 HttpControllerDescriptor, MNJ, HPA 
的 控制 器 选择 过 程 会 试图 基于 类 名 寻找 和 选择 一 个 控制 器 。 


2. 插入 定制 的 控制 器 选择 程序 

虽然 控制 右 选 择 的 默认 逻辑 可 以 满足 大 部 分 Web API 开发 场景 的 需求 ， 但 是 在 某 些 情况 
下 ， 我 们 可 能 需要 提供 一 个 定制 的 选择 策略 。 

为 了 重 写 默 认 的 控制 器 选择 策略 ， 我 们 需要 创建 一 个 新 的 控制 器 选择 程序 服务 ， 然 后 进行 
配置 ， 使 框架 使 用 这 个 服务 。 创 建 一 个 新 的 控制 器 选择 程序 很 简单 ， 我 们 只 需要 编写 一 个 
实现 IHttpControllerSelector 接口 的 类 ，IHttpControllerSelector 接口 定义 如 下 所 示 : 


return controllerDescriptor; 














public interface IHttpControllerSelector 

{ 
HttpControllerDescriptor SelectController(HttpRequestMessage request); 
IDictionary<string, HttpControllerDescriptor> GetControllerMapping(); 


} 
正如 其 方法 名 所 示 ，SelectController 方法 的 主要 作用 是 ， 为 指定 的 HttpRequestMessage 
选择 一 个 控制 器 类 型 ， 并 返回 一 个 HttpControllerDescriptor 对 象 。GetControLLerMapping 
方法 为 控制 器 选择 程序 添加 了 另 一 个 功能 : 返回 一 个 字典 ， 其 中 包含 全 部 控制 器 名 以 及 对 
应 的 HttpControllerDescriptor 对 象 。 但 是 ， 目 前 只 有 ASP.NET Web API 的 API 浏览 器 
使 用 了 这 一 功能 。 




















我 们 通过 HttpConfiguration 对 象 的 Services 集合 ， 配 置 定制 的 控制 器 选择 程序 ， 供 框架 
使 用 。 例 如 : 下 面 一 段 代码 展 示 了 如 何 替换 默认 的 控制 器 选择 程序 ， 不 再 在 类 名 中 寻找 前 
级 Controller ,而 是 使 用 新 的 策略 ， 让 开发 者 指定 一 个 定制 的 前 级 : 
































TEL: 重 写 默 认 控制 器 前 级 的 完整 代码 更 为 复杂 ， 不 仅仅 需要 提供 一 个 新 的 控制 器 选择 程序 。 











控制 器 和 路 由 | 265 


const string controllerSuffix = "service"; 


config.Services.Replace( 
typeof (IHttpControllerSelector), 
new CustomSuffixControllerSelector(config, controllerSuffix)); 








什么 是 默认 服务 ? 


如 果 你 浏览 ASP.NET Web API 的 源 代码 ,会 看 到 在 很 多 代码 中 ,框架 组 件 使 用 配置 对 
象 提供 的 通用 服务 ， 以 获得 实现 了 各 种 框架 服务 接口 的 对 象 。 你 可 能 会 感到 奇怪 ， 这 
些 接口 后 面 的 具体 类 型 是 在 什么 地 方 声 明 的 。 

在 HttpConfiguration 的 构造 函数 中 ， 我 们 可 以 看 到 如 下 声明 : 


Services = new DefaultServices(this); 


我 们 可 以 看 到 ，DefauLtServices 类 是 ServicesContainer 的 一 个 实现 ， 这 个 类 型 用 于 
保存 通用 框架 服务 ， 其 构造 函数 中 设置 了 默认 的 服务 对 象 ， 代 码 如 下 所 示 : 


public DefaultServices(HttpConfiguration configuration) 


{ 


if (configuration == null) 


{ 
} 


throw Error.ArgumentNull("configuration") ; 


_configuration = configuration; 


SetSingle<IActionValueBinder>(new DefaultActionValueBinder()); 
SetSingle<IApiExplorer>(new ApiExplorer(configuration) ); 
SetSingle<IAssembliesResolver>(new DefaultAssembliesResolver()); 
SetSingle<IBodyModelValidator>(new DefaultBodyModelValidator()); 
SetSingle<IContentNegotiator>(new DefauLtContentNegotiator()); 


} 


这 些 默认 的 服务 可 以 作为 一 个 很 好 的 起 点 ， 帮 助 你 探索 框架 的 默认 行为 ， 决 定 是 否 需 
要 替换 其 中 一 个 或 多 个 默认 行为 ， 还 可 以 更 好 地 理解 修改 一 个 特定 行为 需要 替换 什么 
组 件 。 








12.2.4 控制 器 激活 

一 旦 控制 器 选择 程序 找到 一 个 HttpControllerDescriptor 对 象 ， 并 将 其 返回 给 分 发 程 
序 ， 分 发 程序 就 可 以 调用 HttpControLLerDescriptor 的 CreateController 方法 ， 获 得 控 
制 器 的 一 个 实例 。CreateController 转 而 将 创建 和 获得 控制 器 实例 的 任务 委托 给 实现 了 
IHttpControllerActivator 接口 的 一 个 对 象 。 




















IHttpControllerActivator 只 有 一 个 功能 ， 就 是 创建 控制 器 实例 。 其 定义 如 下 : 


public interface IHttpControllerActivator 


{ 
IHttpController Create(HttpRequestMessage request, 
HttpControllerDescriptor controllerDescriptor, 
Type controllerType); 


与 控制 器 选择 类 似 ， 控 制 器 激活 的 默认 逻辑 由 DefaultHttpControllerActivator 类 实现 ， 
并 在 DefaultServices 构造 函数 中 进行 注册 。 





默认 的 控制 器 沿 活 程序 通过 两 个 方法 创建 控制 嚣 对象。 控制 器 激活 程序 首先 尝试 使 用 ASP. 
NET Web API 依赖 关系 解析 程序 (dependency resolver) 创建 一 个 实例 。 依 赖 关系 解析 程 
序 是 IDependencyResolver 接口 的 一 个 实现 ， 为 框架 提供 一 个 通用 机 制 ， 将 任务 外 部 化 ， 
如 创建 对 象 和 管理 对 象 生命 期 。 在 ASP.NET Web API 中 ， 依 赖 关系 解析 程序 也 用 于 插入 
IOC (Inversion-Of-Control， 控 制 反 转 ) 容器 ， 如 Ninject 和 Castle Windsor。 依 赖 关系 解析 
程序 的 实例 通过 HttpConfiguration 对 象 的 DependecnyResolver 属性 ， 向 框架 和 注册， 框架 
会 调用 如 GetService(Type serviceType) 的 方法 ， 创 建 对 象 实例 ， 而 不 会 直接 创建 这 些 类 
型 的 实例 。 这 种 方式 可 以 使 设计 的 耦合 更 松散 ， 提 高 ASP.NET WEb API 框架 本 身 的 可 扩 
展 性 ， 同 样 也 适用 于 你 自己 的 服务 设计 。 


如 有 果 依赖 关系 解析 程序 没有 在 框架 中 注册， 或 者 不 能 创建 所 需 控制 器 类 型 的 实例 ， 那 么 默 
认 的 控制 器 激活 程序 会 尝试 执行 指定 控制 器 类 型 的 无 参数 构造 国 数 ， 创 建 一 个 实例 。 

控制 器 激活 程序 创建 控制 实例 之 后 ， 会 将 控制 器 实例 传 回 控制 器 分 发 程序 ， 然 后 分 发 程序 
对 控制 器 对 象 调用 ExecuteAsync 方法 ， 将 控制 流转 到 控制 器 管道 。 调 用 代码 如 下 : 





























return httpController.ExecuteAsync(controllerContext, cancellationToken); 
和 我 们 讨论 过 的 大 部 分 组 件 一 样 ， 控 制 器 的 ExecuteAsync 是 一 个 异步 方法 ， 返 回 一 个 Task 


实例 。Web API 框架 的 组 件 不 会 因 IO 操作 阻塞 线程 的 执行 ， 从 而 提高 框架 自身 的 吞吐 率 ， 
使 用 有 限 的 计算 资源 处 理 更 多 的 请 求 。 


12.3 控制 器 管道 


消息 处 理 程序 管道 对 HTTP 请 求 和 响应 的 低层 处 理 进行 了 抽象 ， 控 制 器 管道 则 为 开发 者 提 
供 了 高 层 编程 抽象 ， 例 如 : 控制 器 、 操 作 、 模 型 和 筛选 器 。 对 处 理 请 求 和 响应 中 用 到 的 这 
些 对 象 进行 指挥 协调 的 ， 正 是 控制 器 实例 自身 一 一 控制 器 管道 因此 得 名 。 









































12.3.1 ApiController 
在 根本 上 ，ASP.NET Web API 控 制 器 可 以 是 任何 实现 了 IHttpController 接口 的 类 。 
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IHttpController 接口 包含 一 个 异步 执行 方法 ， 默 认 情况 下 由 底层 的 分 发 程序 调用 : 


public interface IHttpController 


{ 

Task<HttpResponseMessage> ExecuteAsync( 
HttpControllerContext controllerContext, 
CancellationToken cancellationToken) ; 

} 


虽然 这 个 接口 因 其 简单 而 具有 极 大 的 灵活 性 ， 但 却 缺乏 ASP.NET 开发 者 惯 于 使 用 的 很 多 功 
能 ， 例 如 身份 验证 功能 、 模 型 绑 定 和 验证 。 为 了 提供 这 些 功能 ， 同 时 又 保持 接口 的 简单 性 ， 
降低 消息 处 理 程序 管道 和 控制 器 管道 之 间 的 而 合 度 的 同时 ，ASP.NET Web API 团队 设计 了 
ApiController 基 类 。ApiController 对 核心 控制 器 抽象 进行 了 扩展 ， 为 派生 类 提供 两 类 服务 : 





。 一 个 处 理 模型 ， 其 中 包含 筛 选 器 、 模 型 绑 定 和 操作 方法 ， 
。 附加 的 上 下 文 对 象 和 帮助 类 ， 甚 中 包含 底层 配置 、 请 求 消息 、 模 型 状态 以 及 其 他 元 素 的 
上 下 文 对 象 。 


12.3.2 ”ApiController 处 理 模型 
ApiController 指挥 的 处 理 模型 由 几 个 不 同 阶 段 组 成 ， 并 且 和 低层 的 消息 处 理 程序 管道 一 
样 ， 提 供 很 多 不 同 的 扩展 点 ， 可 以 为 默认 的 数据 流 提 供 定制 逻辑 。 


大 体 上 ， 控 制 器 管道 可 以 选择 一 个 操作 方法 进行 请 求 处 理 ， 将 请 求 的 属性 映射 到 选中 方法 的 
参数 ， 并 可 以 执行 各 种 算 选 器 类 型 。 通 过 ApiControtter 进行 的 请 求 处 理 大 致 如 图 12-4 所 示 。 








TILI 


YY 











图 12-4: 控制 器 管道 
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与 消息 处 理 程序 管道 类 似 ， 控 制 器 管道 也 构建 一 个 “俄罗斯 套 娃 ”结构 ， 一 个 请 求 从 这 个 
结构 的 最 外 范围 开始 ， 流 经 一 系列 典 套 范围 ， 到 达 最 内 范围 的 操作 方法 。 操 作 方 法 生成 一 
个 响应 ， 该 响应 从 最 内 范围 流 回 到 最 外 范围 。 控 制 右 管道 中 的 范围 是 通过 和 划 选 左 实 现 的 ， 
也 和 消息 处 理 程序 管道 一 样 ， 探 制 器 管道 的 所 有 组 件 都 是 通过 任务 实现 异步 执行 。 例 如 ， 
管道 接口 IActionFilter 就 是 如 此 。 






































public interface IActionFilter : IFilter 


{ 

Task<HttpResponseMessage> ExecuteActionFilterAsync( 
HttpActionContext actionContext, 
CancellationToken cancellationToken, 
Func<Task<HttpResponseMessage>> continuation) ; 

} 

} 





本 章 稍 后 将 详细 介绍 筛选 器 。 我 们 首先 要 讨论 的 是 ， 基 于 请 求 特征 选择 控制 器 上 正确 操作 
的 过 程 。 

1. 操作 选择 

ApiController.ExecuteAsync 方法 内 部 执行 的 首 批 操作 之 一 是 操作 选择 。 操 作 选 择 是 
于 收 到 的 HttpRequestMessage， 进 行 控制 器 方法 选择 的 过 与 控制 器 选择 一 样 ， 


作 选 择 也 委托 给 一 个 类 型 ， 其 主要 任务 就 是 操作 选择 。 这 个 类 型 可 以 是 任何 实现 
IHttpActionSelector 接口 的 类 。IHttpActionSelector pa 








Sek 


public interface IHttpActionSelector 


{ 
HttpActionDescriptor SelectAction(HttpControllerContext controllerContext); 
ILookup<string, HttpActionDescriptor> GetActionMapping( 
HttpControllerDescriptor controllerDescriptor); 
} 


和 HttpControllerSelector 一 样 ，IHttpActionSelector 在 技术 上 有 两 个 功能 : 从 上 下 文选 
择 操作 ， 以 及 提供 操作 映射 的 列表 。 实 现 了 第 二 个 功能 的 操作 选择 程序 就 可 以 由 ASP.NET 
Web API 的 API 浏览 器 功能 所 使 用 。 





通过 明确 替换 默认 的 操作 选择 程序 〈 稍 后 进行 讨论 )， 或 者 使 用 一 个 依赖 关系 解析 程 
序 〈 通 常 与 控制 反 转 容器 一 起 使 用 )， ws 
序 。 例 如 : 下 面 的 代码 使 用 Ninject 控制 反 转 容器 ， 将 默认 的 操作 选择 程序 替换 为 名 为 
CustomActionSelector 的 定制 选择 程序 。 





var kernel = new StandardKernel(); 
kernel.Bind<IHttpActionSelector>().To<CustomActionSelector>(); 


config.DependencyResolver = new NinjectResolver(kerneL) ; 
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为 了 判断 是 否 有 必要 提供 定制 的 操作 选择 程序 ， 你 必须 首先 理解 默认 的 操作 选择 程序 实 
现 的 逻辑 。Web API 提供 的 默认 的 操作 选择 程序 是 ApicontrollerActionSelector， 其 实现 
实际 上 是 一 组 算 选 器 ， 这 些 筛 选 器 的 预期 行为 是 从 一 个 备 选 操作 列表 中 返回 一 个 操作 。 
ApiControllerActionSelector 的 FindMatchingActions 方法 实现 了 这 一 选择 算法 ， 如 图 12-5 所 示 。 




















图 12-5; 默认 操作 选择 程序 逻辑 


在 默认 的 操作 选择 逻辑 中 ， 最 初 的 也 是 最 关键 的 一 点 ， 是 判断 匹配 的 路 由 是 标准 路 由 
( 即 ， 在 Web API 的 全 局 配置 中 ， 通 过 如 MapHttpRoute 的 方法 声明 的 路 由 )， 还 是 使 用 
RouteAttribute 属性 修饰 操作 产生 的 ， 基 于 属性 的 路 由 。 


public class ValuesController 


{ 
[ActionName("do")] 
public string ExecuteSomething() { 


} 

} 
如 果 设 有 找到 匹配 操作 路 由 参数 值 的 操作 方法 ， 选 择 程序 会 返回 一 个 HTTP 响应 404 Not 
Found。 如 有 果 找 到 了 匹配 的 操作 方法 ， 那 么 匹配 的 操作 会 再 次 进行 算 选 ， 去 除 收 到 请 求 相 关 
的 具体 方法 不 适用 的 操作 ， 将 结果 作为 初始 的 操作 备 选 列表 返 


如 果 路 由 数据 没有 明确 指明 操作 方法 ， 那 么 初始 操作 备 选 的 选择 逻辑 会 尝试 从 HTTP 方法 
名 推导 出 操作 名 。 例 如 ， 对 于 一 个 GET 请 求 ， 选 择 程序 会 寻找 名 字 以 字符 串 "GET" 开头 的 





E 
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操作 方法 。 


如 有 果 请 求 与 一 个 基于 属性 的 路 由 匹配 ， 那 么 初始 的 备 选 操作 列表 由 路 由 自身 提供 ， 并 接着 
进行 算 选 ， 去 除 那些 不 适合 所 收 到 请 求 的 HTTP 方法 的 备 选 操作 。 


在 建立 备 选 操作 方法 的 初始 列表 之 后 ， 默 认 操作 选择 逻辑 会 执行 一 系列 的 细 化 ， 将 备 选 操 
作 的 列表 缩短 到 只 剩 下 一 个 。 这 些 细 化 如 下 。 


。 筛选 掉 未 包含 匹配 路 由 所 需 的 参数 集 的 方法 。 

。 精简 备 选 操作 列表 ， 只 保留 评估 顺序 值 最 低 的 操作 。 你 可 以 使 用 RouteAttribute 的 
Order 属性 ， 控 制 基 于 属性 的 路 由 的 备用 操作 的 顺序 。 在 默认 情况 下 ，order 设置 为 零 ， 

因此 这 个 细 化 阶段 会 返回 整个 备 选 操作 集合 。 

。 精简 备 选 操作 列表 ， 只 保留 优先 级 最 高 的 操作 。 优 先 级 用 于 基于 属性 的 路 由 ， 由 
RoutePrecedence.Compute 国 数 ， 根 据 匹 配 的 路 由 ， 计 算得 到 。 

。 将 剩余 的 备 选 操作 列表 按照 参数 数目 分 组 ， 从 参数 最 多 的 组 中 ， 返 回 第 一 个 备 选 操作 。 


到 这 里 ， 备 选 操作 列表 中 应 该 只 剩 下 一 个 操作 。 于 是 ， 默 认 的 操作 选择 程序 执行 一 个 最 终 
检查 ， 根 据 返回 的 备 选 操作 数量 ， 采 取 以 下 三 种 操作 之 一 。 


。 当 返 回 的 备 选 操作 数量 为 0 时 :如 果 存 在 备 选 操作 但 该 操作 不 适用 于 请 求 的 HTTP 方法 ， 
那么 返回 一 个 HTTP 405 消息 ;如 果 设 有 匹配 的 操作 ， 那 么 返回 一 个 HTTP 404 消息 。 

。 当 返 回 的 备 选 操作 数量 为 1 时， 返回 匹配 的 操作 描述 符 ， 用 于 操作 调用 。 

。 当 返 回 的 备 选 操作 数量 >1 时 ， 抛 出 一 个 InvalidOperationException 异常 ， 说 明 存 在 模 
糊 匹 配 。 









































2. 筛选 器 

如 图 12-4 所 示 ， 筷 选 器 提供 一 个 瞳 套 的 范围 集合 ， 用 于 实现 跨越 多 个 控制 器 或 者 操作 的 功 
能 。 虽 然 往 选 器 在 概念 上 相似 ， 但 根据 其 何 时 运行 以 及 访问 的 数据 类 型 ,筛选 器 可 以 分 为 四 
类 : 身份 验证 筛选 器 、 授 权 筛选 器 、 操 作 筛 选 器 和 异常 得 选 器 。 图 12-6 展示 了 这 些 分 类 。 
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图 12-6: 筛选 器 类 
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EREE, Web API 中 的 得 选 器 可 以 是 任何 实现 了 IFilter 接口 的 类 Filter 接口 只 包含 


public interface IFilter 


bool AllowMultiple { get; } 
} 


除了 IFilter 接口 ，Web API 还 提供 一 个 基 类 ， 这 个 基 类 实现 了 IFitter 接口 ， 并 继承 
T -NET 框架 的 Attribute 类 。 因 此 ， 从 这 个 基 类 派生 的 所 有 筛选 器 都 可 以 采用 两 种 方式 
添加 。 首 先 ， 这 些 筛 选 器 可 以 直接 添加 到 全 局 配置 对 象 的 Filters 集合 ， 代 码 如 下 : 





config.Filters.Add(new CustomActionFilter()); 





此 外 ， 从 基 类 FilterAttribute 派生 的 筛选 器 也 可 以 作为 属性 ， 添 加 到 Web API 控制 器 类 
或 者 操作 方法 ， 代 码 如 下 : 
[CustomActionFilter] 


public class ValuesController : ApiController 


{ 
} 


无 论 通过 哪 种 方式 加 到 Web API M A, tii ve at AB PR TF TE HttpConfiguration. Filters 
BAH, PEA ii ue EH Filter 对 象 集 合 进行 存储 。 这 种 泛 型 设计 使 得 
HttpConfiguration 对 象 可 以 包含 很 多 不 同类 型 的 筛选 器 ， 其 中 包括 四 种 类 型 (身份 验 
证 筛选 器 、 授 权 筛 选 器 、 操 作 筛 选 器 和 异常 筛选 器 ) 之 外 的 筛选 器 类 型 。 我 们 可 以 创建 
新 筛选 器 类 型 ， 并 添加 到 Httpconfiguration 中 ， 既 不 会 破坏 应 用 程序 ， 也 不 需要 修改 
HttpConfiguration。 随 后 ， 这 些 新 筛选 器 类 型 可 以 由 定制 的 新 控制 器 类 型 发 现 并 运行 。 


ApiController 根据 如 下 条 件 ， 对 筛选 器 的 排序 和 执行 进行 协调 : 





。 季 选 器 类 型 
ApiController 按照 类 型 对 筛选 器 分 组 ， 将 每 个 组 作为 不 同 的 能 套 范围 执行 〈 参 见 
图 12-4) 。 





。 适用 处 

作为 全 局 配置 (HttpConfiguration.Filters.Add(...)) 的 一 部 分 添加 的 筛选 器 首先 添加 到 
Filters 集合 中 ， 作 为 类 属性 (ActionFilterAttribute, AuthorizationFilterAttribute 和 
ExceptionFilterAttribute) 或 操作 方法 属性 添加 的 算 选 器 随后 添加 。 在 通过 属性 添加 
的 盘 选 器 中 ， 控 制 器 类 属性 的 筛选 绒 首先 添加 ， 操 作 方 法 属性 的 盘 选 绒 随后 添加 。 算 选 
器 运行 的 顺序 与 添加 顺序 相同 。 因 此 ， 全 局 添加 的 筛选 器 首先 运行 ， 接 着 是 通过 控制 器 
属性 添加 的 盘 选 器 ， 最 后 是 通过 操作 方法 属性 添加 的 筛选 器 。 
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。 添加 顺序 
科 选 右 在 分 组 之 后 ， 在 组 内 按照 添加 顺序 执行 。 


3. 身份 验证 筛选 器 

身份 验证 筛选 器 有 两 个 功能 。 首 先 ， 当 请 求 流 经 管道 时 ， 身 份 验证 筛选 器 对 请 求 进行 检 
查 ， 验 证 一 组 声明 ， 建 立 调用 用 户 的 身份 。 如 果 不 能 从 提供 的 声明 建立 用 户 身 份 ， 身 份 验 
证 筛选 器 也 可 以 用 于 修改 响应 ， 向 用 户 代 理 提 供 关 于 建立 用 于 身份 的 进一步 指示 。 这 种 响 
应 称 为 质询 响应 (challenge response)。 第 15 章 将 详细 讨论 身份 验证 筛选 器 。 



































4. 授权 筛选 器 
授权 筛选 器 执行 访问 策略 ， 强 制 用 户 、 客 户 端 应 用 程序 或 其 他 对 象 ( 指 安全 对 象 ) 对 
Web API 提供 的 HTTP 资源 或 资源 组 的 访问 层次 。 在 技术 上 ， 一 个 授权 筛选 器 就 是 实现 了 
IAuthorizationFilter 接口 的 类 。IAuthorizationFilter 接口 只 包含 一 个 异步 运行 饰 选 器 
的 方法 : 
Task<HttpResponseMessage> ExecuteAuthorizationFilterAsync( 
HttpActionContext actionContext, 


CancellationToken cancellationToken, 
Func<Task<HttpResponseMessage>> continuation) ; 








FE PR IZ Fy PLAN iE BS AME — 4 ee AE Ss TAuthorizationFilter 接口 ， 但 是 [Authorization 
Filter 接口 并 不 是 开发 者 最 易 使 用 的 编程 模型 一 一 这 主要 是 由 异步 编程 和 .NET 框架 
任务 API 的 复杂 性 导致 的 。 因 此 ，Web API 提 供 了 AuthorizationFilterAttribute 类 。 
AuthorizationFilterAttribute 实现 了 IAuthorizationFilter 接口 和 ExecuteAuthorization 
FilterAsync 方法 ， 提 供 如 下 的 虚拟 方法 ， 可 以 由 派生 类 重 写 : 





























public virtual void OnAuthorization(HttpActionContext actionContext); 


AuthorizationFilterAttribute 在 自己 的 ExecuteAuthorizationFilterAsync 方 法 中 调用 了 
OnAuthorization 方法 ， 使 我 们 可 以 用 更 熟悉 的 同步 风格 编写 派生 的 授权 筛选 器 。 在 调用 
OnAuthorization 之 后 ， 基 类 检查 HttpActionContext 对 象 的 状态 ， 由 此 做 出 判断 ， 是 继续 进 
行 请 求 处 理 ， 还 是 返回 一 个 新 的 Task， 其 中 包含 新 的 表示 授权 失败 的 HttpResponseMessage。 









































当 你 编写 派生 自 AuthorizationFilterAttribute 的 定制 授权 筛选 器 时 ， 要 表示 授权 失败 ， 
可 以 将 actionContext.Response 设置 为 一 个 HttpResponseMessage 对 象 ， 代 码 如 下 所 示 : 


public class CustomAuthFilter : AuthorizationFilterAttribute 


{ 
public override void OnAuthorization(HttpActionContext actionContext) 
{ 
actionContext.Response = actionContext.Request.CreateErrorResponse( 
HttpStatusCode.Unauthorized, "denied"); 
} 
} 
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当 OnAuthorize 调用 结束 后 ，AuthorizationFilterAttribute 类 使 用 下 面 的 代码 ， 分 析 上 下 
文 状态 ， 然 后 继续 进行 处 理 或 者 立即 返回 响应 : 


if (actionContext.Response != null) 
{ 
return TaskHelpers.FromResuLt(actionContext.Response) ; 
} 
else 
{ 
return continuation(); 
} 




















此 外 ， 如 果 OnAuthorize 调用 抛 出 一 个 异常 ，AuthorizationFiLterAttribute 会 捕获 这 个 异 
常 ， 终 止 处 理 ， 返 回 一 个 响应 码 为 500 Internal Server Error AY HTTP 响应 : 




















try 
{ 
OnAuthorization(actionContext) ; 
} 
catch (Exception e) 
{ 
return TaskHelpers.FromError<HttpResponseMessage>(e); 
} 


4 PR ie Lb A SG BL — 7 ait AY Be A Ea t, — FF te BT A A Web API 提 供 的 现 有 的 
AuthorizeAttribute, AuthorizeAttribute 使 用 Thread.CurrentPrincipal žk 得 认证 用 
户 的 身份 (可 能 还 有 角色 成 员 信息 )， 与 属性 构造 函数 中 提供 的 策略 信息 进行 比较 。 还 
有 一 个 有 趣 的 细节 要 注意 : AuthorizeAttribute 会 检查 操作 方法 及 其 控制 器 的 Allow 
AnonymousAttribute 属性 ， 如 果 属 性 存在 ， 就 成 功 退 出 。 


5. 操作 筛选 器 
操作 筛选 器 在 概念 上 与 授权 筛选 器 极为 相似 。 实 际 上 ，IActionFilter 的 执行 方法 的 签名 
与 IAuthorizationFilter 中 对 应 的 方法 签名 是 一 样 的 。 











Task<HttpResponseMessage> IActionFilter.ExecuteActionFilterAsync( 
HttpActionContext actionContext, 
CancellationToken cancellationToken, 
Func<Task<HttpResponseMessage>> continuation) 


face, PRIE Tir ae ae SCAM Mita ee ALA TZ Sth SAS Te] Zh Ba ite as EY Vd FE 
DL. RARE., ieee Ea WET, IRA EAS TIL TT. BCA tie at 
首先 运行 ， 然 后 是 操作 筛选 器 ， 最 后 是 异常 筛选 器 

















第 二 个 不 同 之 处 是 操作 筛选 器 与 其 他 两 种 筛选 器 最 显著 的 不 同 : 开发 者 可 以 在 操作 方法 
调用 的 前 后 进行 请 求 处 理 。 这 个 功能 是 通过 ActionFilterAttribute 类 中 下 面 两 个 方法 提 
供 的 。 























public virtual void OnActionExecuting(HttpActionContext actionContext); 


public virtual void OnActionExecuted( 
HttpActionExecutedContext actionExecutedContext) ; 








FUEL (th 3s 7 AY iE — RE, ActionFilterAttribute 实现 了 IActionFilter 接口 ， 对 直接 使 
用 Task 的 复杂 度 进 行 抽象 ， 同 时 也 继承 了 Attribute, Mimi HE PR(E iiie ar AT EEH E 


控制 器 类 和 操作 方法 上 。 


作为 开发 者 ， 你 可 以 简单 地 从 ActionFilterAttribute 进行 派生 ， 重 写 OnActionExecuting 
和 /或 0nActionExecuted 方法 ， 很 容易 地 创建 操作 算 选 器 。 例 如 ， 示 例 12-3 对 操作 方法 进 


行 了 一 些 基 本 的 审计 操作 。 
示例 12-3: 审核 操作 方法 的 操作 筛选 器 示例 


public class AuditActionFilter : ActionFilterAttribute 


{ 
public override void OnActionExecuting(HttpActionContext c) 
{ 

Trace. TraceInformation("Calling action {0}::{1} with {2} arguments", 
c.ControllerContext.ControllerDescriptor.ControllerName, 
c.ActionDescriptor.ActionName, 
c.ActionArguments.Count) ; 

} 
public override void OnActionExecuted(HttpActionExecutedContext c) 
{ 

object returnVal = null; 

var oc = c.Response.Content as ObjectContent; 

if (oc != null) 
returnVal = oc.Value; 

Trace. TraceInformation("Ran action {0}::{1} with result {2}", 
c.ActionContext.ControllerContext.ControllerDescriptor.ControllerName, 
c.ActionContext.ActionDescriptor .ActionName, 
returnVal ?? string.Empty); 

} 
} 


如 果 操 作 筛 选 器 中 抛 出 一 个 异常 ， 那 么 ActionFilterAttribute 会 创建 一 个 包含 错误 信息 的 
Task<HttpResponseMessage>， 从 而 终止 管道 中 其 他 组 件 执行 的 请 求 处 理 。 这 种 做 法 与 前 面 介 
绍 的 授权 筛选 器 的 处 理 逻 辑 一 致 。ActionFilterAttribute 也 包含 额外 的 逻辑 ， 当 筛选 器 的 
OnActionExecuted 方法 抛 出 异常 时 ， 将 啊 应 消息 的 上 下 文 设 置 为 空 ， 具 体 做 法 很 简单 : 将 








OnActionExecuted 调用 封装 在 一 个 try. .catch 块 中 ， 在 catch 块 中 将 响应 设 为 null, 


try 
{ 


OnActionExecuted(executedContext) ; 
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catch 


{ 
actionContext.Response = null; 
throw; 


} 


6. 异常 篇 选 器 

正如 这 个 科 选 器 名 字 表 明 的 ， 异 常 算 选 器 存在 的 目的 是 对 控制 器 管道 中 抛 出 的 异常 进行 定 
制 处 理 。 与 授权 得 选 器 和 操作 筛选 器 一 样 ， 异 常 盘 选 器 是 通过 实现 IExceptionFilter 接口 
定义 的 。 另 外 ， 框 架 还 提供 基 类 ExceptionFilterAttribute， 以 实现 NET 框架 属性 功能 ， 
并 为 其 派生 类 提供 一 个 更 为 简化 的 编程 模型 。 


在 防止 服务 泄露 可 能 的 敏感 信息 时 ， 蜡 常 筛选 器 极为 有 用 。 例 如 ， 数 据 库 异 常 通常 包含 ; 
据 库 服务 器 或 数据 库 模式 设计 的 详细 信息 ， 攻 击 者 可 能 利用 这 些 信息 ， 对 你 的 服务 器 发 
攻击 。 下 面 是 一 个 异常 筛选 器 示例 ， 这 个 筛选 器 将 异常 的 详细 信息 记录 在 .NET 框架 的 
断 系 统 中 ， 然 后 返回 一 个 通用 的 错误 响应 。 
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public class CustomExceptionFilter : ExceptionFilterAttribute 


{ 


public override void OnException( 
HttpActionExecutedContext actionExecutedContext) 


{ 
var x = actionExecutedContext.Exception; 
Trace.TraceError(x.ToString()); 
var errorResponse = actionExecutedContext.Request.CreateErrorResponse( 
HttpStatusCode.InternalServerError, 
"Please contact your server administrator for more details."); 
actionExecutedContext.Response = errorResponse; 
} 
WRAAE EASE, BT EPS Hill a BGR PRE), SAE TA 
的 方法 : 








[CustomExceptionFilter ] 
public IEnumerable<string> Get() 


{ 


throw new Exception("Here are all of my users credit card numbers..."); 


} 


这 将 会 向 客户 端 返回 一 个 “删节 版 ”的 错误 消息 : 





$ curl http://localhost:54841/api/values 
{"Message":"Please contact your server administrator for more details."} 























但 是 ， 如 果 异 常 筛 选 器 抛 出 一 个 异常 会 怎样 ? 更 宽泛 地 说 ， 如 果 没 有 异常 筛选 器 会 怎样 ? 
未 处 理 的 异常 最 终 会 在 哪里 捕获 ?答案 是 HttpControLterDispatcher。 如 果 你 还 记得 ， 本 
章 前 面 曾 介绍 过 ， 在 默认 情况 下 HttpControllerDispatcher 是 消息 处 理 程序 管道 中 的 最 
后 一 个 组 件 ， 负 责 调 用 Web API 控制 器 的 ExecuteAsync H}. mi H., HttpController 
Dispatcher 将 这 个 ExecuteAsync 调用 封装 在 try. .catch 块 中 ， 代 码 如 下 所 示 : 









































protected override async Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, CancellationToken cancellationToken) 


{ 
try 


{ 
} 


catch (HttpResponseException httpResponseException) 


{ 
} 


catch (Exception exception) 


{ 


return await SendAsyncCore(request, cancellationToken) ; 


return httpResponseException.Response; 


return request.CreateErrorResponse(HttpStatusCode. InternalServerError, 
exception); 


} 


如 你 所 见 ， 这 个 分 发 程序 可 以 返回 附 在 HttpResponseException 上 的 HttpResponseMessage。 
而 且 ， 分 发 程序 包含 一 段 通用 的 异常 处 理 代码 ， 当 捕获 到 未 处 理 的 异常 时 ， 异 常 处 理 代码 
将 这 个 异常 转换 成 一 个 HttpResponseMessage， 消 息 中 包含 异常 的 具体 信息 以 及 HTTP 响应 
码 500 Internal Server Error, 























7. 模型 绑 定 和 验证 

第 13 章 将 重点 讨论 模型 绑 定 ， 我 们 在 此 就 不 做 歼 述 了 。 但 是 对 于 控制 器 管道 而 言 ， 有 一 
点 非常 重要 : 模型 绑 定 恰好 发 生 在 行为 筛选 右 处 理 之 前 ， 如 下 面 的 ApiController 源 代码 
片段 所 示 : 

















private async Task<HttpResponseMessage> ExecuteAction( 
HttpActionBinding actionBinding, HttpActionContext actionContext, 
CancelLlationToken cancellationToken, IEnumerable<IActionFilter> actionFilters, 
ServicesContainer controllerServices) 


{ 


await actionBinding.ExecuteBindingAsync(actionContext, cancellationToken); 
_modelState = actionContext.ModelState; 


~ 


这 个 顺序 非常 重要 ， 因 为 这 意味 着 行为 筛选 器 可 以 使 用 模型 状态 ， 简 化 一 些 工 作 ， 例 如 ， 
构建 一 个 行为 筛选 器 ， 在 模型 状态 无 效 时 自动 返回 HTTP 响应 400 Bad Request。 这 样 一 
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来 ， 我 们 不 再 需要 在 每 个 PUT 和 POST 行为 方法 中 播 入 如 下 代码 了 : 


public void Post(ModelValue v) 


{ 
if (!ModelState. IsValid) 


{ 
var e = Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState) ; 
throw new HttpResponseException(e); 


} 
} 


相反 ， 我 们 可 以 在 一 个 简单 的 操作 筛选 器 中 进行 这 种 模型 状态 检查 ， 代 码 如 示例 12-4 
所 示 。 


示例 12-4: 模型 状态 验证 筛选 器 
public class VerifyModelState : ActionFilterAttribute 


{ 


public override void OnActionExecuting(HttpActionContext actionContext) 


{ 


if (!actionContext.ModelState. IsValid) 


{ 
var e = actionContext.Request.CreateErrorResponse( 
HttpStatusCode.BadRequest, actionContext.ModelState) ; 
actionContext.Response = e; 
} 
} 
} 


aa 
控制 器 管道 的 最 后 一 步 是 在 控制 器 上 调用 选中 的 操作 方法 。 这 个 任务 由 一 个 特殊 


的 Web API 组 件 操作 调用 程序 (action invoker) 完成 。 操 作 调 用 程序 可 以 是 实现 了 
IHttpActionInvoker 接口 的 任何 类 。IHttpActionInvoker 接口 签名 如 下 : 





public interface IHttpActionInvoker 


{ 
Task<HttpResponseMessage> InvokeActionAsync( 
HttpActionContext actionContext, CancellationToken cancellationToken) ; 


} 


ApiController 从 DefaultServices 请 求 操作 调用 程序 ， 这 意味 着 你 可 以 用 DefaultServices 
的 Replace 方 法， 或 者 依赖 注入 框架 和 it 替换 操作 调用 程序 。 但 是 ， 
Web API 框架 提供 的 默认 实现 ApiControLLerActionInvoker ， 应 该 能 够 满足 大 部 分 的 需 
默认 调用 程序 执行 两 个 主要 功能 ， 如 下 面 的 代码 所 示 : 
object actionResult = await actionDescriptor.ExecuteAsync(controllerContext, 
actionContext.ActionArguments, 


cancellationToken) ; 


return actionDescriptor.ResultConverter.Convert(controllerContext, actionResult) ; 





正如 你 所 预期 的 ， 默 认 调用 程序 的 第 一 个 功能 是 调用 选中 的 操作 方法 。 第 二 个 功能 是 将 操 
作 方 法 调用 的 结果 转换 成 一 个 HttpResponseMessage。 为 了 实现 第 二 个 功能 ， 调 用 程序 使 
用 了 一 个 特殊 的 对 象 ， 操 作 方 法 转换 器 (action result converter) 。 操 作 方 法 转换 器 实现 了 
TActionResultConverter 接口 ， 这 个 接口 只 包含 一 个 方法 ,该 方法 参数 为 一 些 上 下 文 数据 ， 
返回 一 个 HttpResponseMessage。 目 前 ，Web API 包含 三 种 操作 结果 转换 器 : 

















e ResponseMssageResultConverter 


当 操作 方法 直接 返回 HttpResponseMessage 时 使 用 ， 直 接 传 回响 应 消息 。 





e ValueResultConverter<T> 


当 操 作 方 法 返回 一 个 NET 框架 标准 类 型 时 使 用 ， 使 用 相关 的 HttpRequestMethod 的 


CreateResponse<T> 方法 ， 创 建 一 个 HttpResponseMessage。 








e VoidResultConverter 


当 操作 方法 返回 值 为 空 时 使 用 ， 创 建 一 个 新 的 HttpResponseMessage， 状 态 码 为 204 No 


Content, 


操作 方法 的 返回 值 转换 为 HttpResponsemessage 之 后 ， 这 个 消息 就 可 以 开始 反 向 流出 控制 
器 和 消息 处 理 程 序 管道 ， 然 后 传送 给 客户 闻 。 








12.4 小结 


本 章 ， 我 们 深入 探索 了 ASP.NET Web API 中 进行 请 求 处 理 的 两 个 管道 : 低层 的 消息 处 
理 程 序 管道 和 控制 右 管 道 。 这 两 种 管道 各 有 利弊 。 例 如 ， 消 息 处 理 程序 管道 在 请 求 处 理 
的 早期 执行 ， 因 此 适合 终止 执行 代价 较 高 的 代码 路 径 ， 但 随 之 而 来 的 代价 是 ， 你 必须 在 
HttpRequestMessage 和 HttpResponseMessage 层次 工作 。 另 一 方面 ， 探 制 器 管道 为 其 组 件 
提供 了 较 高 层次 的 编程 模型 对 象 ， 例 如 描述 控制 器 、 操 作 方 法 和 相关 属性 的 对 象 。 这 两 种 
管道 都 提供 一 整套 默认 的 组 件 ， 以 及 灵活 的 模型 ， 可 以 使 用 HttpConfiguration 或 定制 的 
DependencyResolver 进行 扩展 。 
































在 下 一 章 ， 我 们 将 更 深入 地 讨论 组 成 消息 处 理 器 管道 的 核心 构件 ， 其 中 有 消息 处 理 程 序 自 
身 ， 也 有 HTTP 原始 类 型 HttpRequestMessage 和 HttpResponseMessage, 
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任何 人 都 能 写 出 计算 机 可 以 理解 的 代码 ， 但 只 有 好 的 程序 员 才 能 写 出 人 工 可 读 的 代码 。 


之 前 我 们 讨论 过 ， 使 用 媒体 类 型 及 其 语义 ， 表 示 系 统 中 领域 空间 的 概念 。 一 旦 涉及 具体 实 
现 ， 这 些 抽象 概念 就 必须 翻译 为 程序 员 能 理解 的 术语 。 对 于 ASP.NET Web API， 这 些 抽象 
概念 的 最 终 表 示 就 是 对 象 ， 或 者 更 准确 地 说 ， 模 型 。 模 型 代表 了 一 种 抽象 层次 ， 开 发 者 使 
用 模型 将 对 象 映 射 到 媒体 类 型 表示 ， 或 者 HTTP 消息 的 其 他 不 同 部 分 。 














ASP.NET Web API 中 的 模型 绑 定 (model binding) 基础 结构 为 我 们 提供 了 进行 这 些 映射 必 
需 的 运行 时 服务 。 有 了 模型 绑 定 ， 开 发 者 可 以 专注 于 Web API 的 实现 细节 ， 将 所 有 的 序列 
化 问题 留 给 框架 处 理 。 使 用 这 种 架构 有 一 个 显而易见 的 好 处 ， 开 发 者 可 以 使 用 单个 抽象 层 
次 ， 即 模型 ， 根 据 Web API 的 不 同 使 用 者 的 需求 ， 支 持 各 种 媒体 类 型 。 例 如 ， 在 问题 跟 
踪 应 用 程序 中 ， 我 们 使 用 表示 问题 的 单个 模型 类 ， 这 个 类 可 以 由 框架 转换 成 不 同 的 媒体 类 
型 ， 如 JSON 或 XML。 














本 章 将 探索 模型 绑 定 ， 详 细 介 绍 不 同 的 运行 时 组 件 ， 以 及 框架 提供 的 扩展 性 挂 钧 
(extensibility hook) ， 用 于 定制 或 添加 新 的 模型 绑 定 功能 。 


13.1 ASP.NET Web API 中 模型 的 重要 性 

一 般 来 说 ， 解 决 单个 问题 的 控制 器 操作 ， 从 长 远 来 看 比较 容易 测试 、 扩 展 和 维护 。 将 消息 
表示 转换 成 模型 对 象 ， 就 是 应 该 首先 从 操作 实现 中 移出 的 问题 之 一 。 请 看 示例 13-1， 代 码 
中 混合 了 序列 化 处 理 和 Web API 操作 的 实现 。 
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示例 13-1: 包含 序列 化 的 操作 
public HttpResponseMessage Post(HttpRequestMessage request) // <1> 
{ 


int id = int.Parse(request.RequestUri.ParseQueryString().Get("id")); // <2> 
var values = request.Content.ReadAsFormDataAsync().Result // <3> 
var issue = new Issue 

Id = id, 

Name = values["name"], 


Description = values["description" ] 


}; 


// 处 理 已 构建 的 问题 
} 


这 段 代码 有 儿 个 明显 的 问题 ， 如 下 。 





。 控制 器 方法 的 签名 非常 通用 ， 如 果 不 查 看 实现 细 广 ， 我 们 很 难 推测 这 个 方法 的 用 途 ， 也 
无 法 使 用 不 同 的 参数 重 载 Post 方法 ， 以 支持 多 个 场景 。 

。 代码 没有 检查 查询 字符 串 中 的 参数 是 否 存在 ， 或 者 是 否 能 转换 成 整数 。 

。 代码 将 实现 绑 定 到 单个 媒体 类 型 (appLication/form-urt-encoded) ， 而 且 执 行 线程 无 法 
同步 读 取 正文 内 容 。 对 于 最 后 一 点 ， 直 接 调用 异步 任务 的 Result 属性 而 不 检查 其 是 否 
完成 ， 可 能 会 阻止 执行 线程 返回 线程 池 处 理 新 的 请 求 ， 因 此 不 是 好 的 做 法 。 






































我 们 可 以 只 使 用 一 个 模型 类 ， 很 容易 地 重 写 这 个 操作 方法 ， 避 免 以 上 问题 ， 如 代码 13-2 所 示 。 
示例 13-2: 使 用 模型 绑 定 的 操作 


public void Post(Issue issue) // <1> 
{ 
// 处 理 已 构建 的 问题 
} 
如 你 所 见 ， 所 有 的 序列 化 处 理 都 从 实现 中 消失 了 ， 操 作 中 只 保留 了 关键 的 代码 。Web API 
框架 中 的 模型 绑 定 基础 结构 会 在 执行 这 个 操作 时 处 理 其 他 的 问题 。 


13.2 ”模型 绑 定 如何 工 作 


模型 绑 定 基础 结构 的 最 核心 部 分 ， 是 一 个 称 为 HttpParameterBinding 的 组 件 ， 这 个 组 件 
知道 如 何 从 一 个 请 求 消息 得 到 参数 值 (参见 示例 13-3)。 每 个 HttpParaneterBinding 实 
例 都 和 一 个 参数 联系 在 一 起 ， 这 个 参数 在 Web API 执行 操作 时 用 HttpConfiguration 
进行 定义 。HttpParameterBinding 实例 如 何 联系 到 一 个 参数 ， 是 由 另 一 个 配置 类 
HttpParameterDescriptor 决定 的 ， 这 个 配置 类 包含 了 描述 参数 的 元 数据 ， 即 参数 名 、 类 
型 ， 或 者 模型 绑 定 基础 结构 可 以 用 来 选择 HttpParameterBinding 的 其 他 任何 属性 。 
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示例 13-3: HttpParameterBinding 操作 


public abstract class HttpParameterBinding 


{ 


protected HttpParameterBinding(HttpParameterDescriptor descriptor); 


public abstract Task ExecuteBindingAsync(ModelMetadataProvider metadataProvider, 
HttpActionContext actionContext, CancellationToken cancellationToken); // <1> 


} 

















示例 13-3 展示 了 HttpParameterBinding 的 基本 结构 ， 其 中 关键 方法 是 ExecuteBinding 
Async, HttpParameterBinding 中 每 个 实现 都 必须 实现 这 个 方法 ， 以 执行 参数 绑 定 。 


和 ASP.NET Web API 中 的 很 多 运行 时 组 件 一 样 ，HttpParameterBinding 也 为 其 核心 方法 
ExecuteBindingAsync 提供 异步 的 方法 签名 。 如 果 你 有 一 个 实现 ， 它 不 依赖 于 从 当前 请 求 消 
息 歼 取 的 值 ， 而 是 执行 一 些 VO 操作 ， 例 如 查询 数据 库 或 者 读 取 文件 ， 那 么 这 个 异步 方法 
就 会 很 有 用 。 示 例 13-4 展示 了 HttpParameterBinding 的 一 个 基本 实现 ， 从 执行 线程 的 区 域 
性 集合 ， 进 行 操作 参数 中 CultureInfo 类 型 参数 的 绑 定 。 











示例 13-4: HttpParameterBinding 实现 


public class CultureParameterBinding : HttpParameterBinding 


{ 


public CultureParameterBinding(HttpParameterDescriptor descriptor) // <1> 
: base(descriptor) 


{ 

} 

public override System. Threading. Tasks. Task 
ExecuteBindingAsync(System.Web.Http.Metadata.ModelMetadataProvider 
metadataProvider, HttpActionContext actionContext, 


System. Threading.CancellationToken cancellationToken) 


{ 


CultureInfo culture = Thread.CurrentThread.CurrentCulture; // <2> 
SetValue(actionContext, culture); // <3> 


var tsc = new TaskCompletionSource<object>(); // <4> 
tsc.SetResuLlt(null); 
return tsc.Task; 


} 
} 


HttpParameterBinding 的 实例 创建 时 使 用 一 个 描述 符 。 我 们 的 实现 忽略 了 这 个 参数 ， 但 是 
别 的 实现 可 能 会 用 到 这 个 参数 的 一 些 信息 <1>。ExecuteBindingAsync 方法 从 当前 线程 中 获 
得 CultureInfo 实例 <2>， 并 调用 基 类 中 的 SetValue 方 法， 使 用 获得 的 CultureInfo 实例 
设置 绑 定 <3>。ExecuteBindingAsync 方法 在 最 后 创建 了 一 个 TaskCompLetionSource， 用 于 
返回 已 经 同步 完成 的 新 任务 <4>。 在 这 个 方法 的 异步 版 本 中 ，SetValue 可 能 会 作为 返回 任 
务 的 一 部 分 调用 。 











我 们 现在 可 以 使 用 这 个 CultureParameterBinding， 将 一 个 CultureInfo 实例 直接 作为 操作 
方法 的 参数 传 入 ， 如 示例 13-5 所 示 。 








示例 13-5: 以 CultureInfo 实例 为 参数 的 Web API 操作 
public class HomeController : ApiController 


{ 
[HttpGet] 
public HttpResponseMessage BindCulture(CultureInfo culture) 


{ 
return Request.CreateResponse(System.Net.HttpStatusCode.Accepted, 
String.Format("BindCulture with name {0}.", culture.Name)); 


} 


你 现在 了 解 了 HttpParameterBinding 是 什么 , 但 是 我 们 还 没有 讨论 ， 当 操作 执行 时 ， 框 
架 如 何 配置 和 选择 HttpParameterBinding, HttpParameterBinding 的 选择 是 在 框架 中 可 用 
的 诸多 可 插入 服务 之 一 ，System.Web.Http.ModelBinding.IActionValueBinder 中 完成 的 ， 
IActionValueBinder 的 默认 实现 是 System.Neb.Http.ModeLBinding.DefauLtActionVaLue 
Binder, IActionValueBinder 负责 返回 一 个 HttpActionBinding 实例 ， 这 个 实例 主要 包含 与 
间 定 控制 器 操作 相关 的 HttpParameterBinding 实例 集合 ， 这 个 集合 可 以 进行 缓存 ， 供 多 个 
请 求 使 用 。 





public interface IActionValueBinder 


{ 


HttpActionBinding GetBinding(HttpActionDescriptor actionDescriptor); 


} 





DefaultActionValueBinder 的 内 建 实现 使 用 了 反射 机 制 ， 构 建 一 个 HttpParameter Descriptor 
列表 ， 用 于 之 后 的 配置 查询 和 HttpParamterBinding 实例 的 选择 (参见 图 13-1). 









public int Post(Issue issue) 


HttpParameterDescriptor HttpParameterDescriptor 
Name = Name = issue 
Type = System.Int32 Type = WebApiBook. Issue 





HttpParameterBinding HttpParameterBinding 











13-1; HttpParameterBinding 选择 


H ij, DefaultActionValueBinder 支持 两 种 不 同 的 方式 ， 判 断 与 一 个 操作 关联 的 是 哪 
个 HttpParameterBinding, 第 一 种 方式 通过 使 用 HttpConftguration 对 象 的 Parameter 
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BindingRules 属性 建立 关联 ， 这 个 属性 提供 了 一 组 规则 ， 用 于 为 一 个 指定 的 HttpParameter 
Descriptor 选择 绑 定 实例 。 这 些 规则 的 形式 是 一 个 委托 Func<HttpPara meterDescriptor ,Htt 
pParameterBinding>， 这 个 委托 以 描述 符 为 参数 ， 返 回 一 个 绑 定 实例 。 这 意味 着 ,你 可 以 提供 
一 个 方法 回调 ， 或 者 一 个 Lamda 表达 式 ， 用 于 绑 定 的 解析 。 对 于 CultureParameterBinding, 
我 们 需要 定义 一 个 规则 ， 为 与 类 型 System.Globalization.CultureInfo 相 关联 的 
HttpParameterDescriptor 返回 CultureParameterBinding， 代 码 如 示例 13-6 所 示 。 





























示例 13-6: 使 用 规则 配置 HttpParameterBinding 


config.ParameterBindingRules.Insert(0, (descriptor) => // <1> 


if (descriptor.ParameterType == typeof(System.Globalization.CultureInfo)) // <2> 
return new CultureParameterBinding(descriptor); 


return null; 


Fs 


这 个 插入 的 新 规则 使 用 一 个 Lambda 表达 式 <1>， 检 查 描述 符 的 ParameterType 属性 ， 只 有 
当 类 型 为 System.Globalization.CultureInfo 时 才 返回 我 们 的 绑 定 <2>。 








第 二 种 机 制 是 声明 性 的 ， 用 到 一 个 属性 ParameterBindingAttribute。 使 用 这 种 机 制 ， 我 们 
需要 派生 这 个 属性 〈 详 见 下 一 节 )。 


如 果 没 有 找到 映射 规则 或 者 ParameterBindingAttribute， 系 统 会 使 用 一 种 默认 策略 ， 将 简 
单 类 型 绑 定 到 URI 片段 或 查询 字符 串 变 量 ， 将 复杂 类 型 绑 定 到 请 求 正 文 。 


13.3 内 建 的 模型 绑 定 器 


ASP.NET Web API 框架 自 带 几 个 内 建 的 绑 定 器 实现 ， 但 是 对 于 开发 者 来 说 ， 只 有 三 
个 绑 定 器 值得 特别 注意 : ModelBindingParameterBinder, FormatterParameterBinder 
和 HttpRequestParameterBinding。 这 个 三 个 绑 定 器 以 完全 不 同 的 方式 ， 实 现 了 消息 各 
部 分 到 模型 的 绑 定 。 第 一 个 绑 定 器 ModelBindingParameterBinder, 借用 了 ASP.NET 
MVC 的 一 种 方式 ， 将 消息 的 不 同 部 分 像 乐 高 玩具 块 一 样 进行 组 合 ， 形 成 模型 。 第 二 个 
FormatterParameterBinder， 依 赖 于 格式 化 程序 ， 理 解 给 定 媒体 类 型 的 全 部 语义 和 格式 ， 并 
知道 如 何 应 用 这 些 语义 进行 模型 的 序列 化 或 者 反 序列 化 。 格 式 化 程序 代表 了 内 容 协 商 的 一 
个 关键 部 分 ， 是 首选 的 绑 定 方式 。 最 后 ， 第 三 个 HttpRequestParameterBinding， 用 于 支持 
那些 直接 在 方法 签名 中 使 用 HttpRequestMessage 或 HttpResponseMessage 实例 的 操作 。 














13.3.1 ModelBindingParameterBinder 

ModelBindingParameterBinder 的 实现 重用 了 ASP.NET MVC 中 进行 模型 绑 定 的 方法 。 在 这 
种 方法 中 ， 值 提供 程序 从 HITP 消息 的 不 同 部 分 获得 数据 ， 由 模型 绑 定 器 把 这 些 部 分 组 合 
成 为 模型 。 
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这 种 实现 主要 关注 简单 的 键 / 值 对 的 绑 定 ， 例 如 : HTTP 标 头 中 的 键 / 值 、URL 片段 、 查 
询 字 符 串 或 者 用 application/form-url-encoded (用 于 对 HTTP 表单 进行 编码 的 媒体 类 型 ) 
编码 的 正文 。 这 些 值 通 常 都 是 消息 中 的 字符 串 ， 并 可 以 转换 成 基本 类 型 。 模 型 绑 定 器 并 不 
知道 媒体 类 型 的 具体 信息 ， 也 不 知道 如 何 解释 媒体 类 型 ， 这 些 是 格式 化 程序 (formatter) 
的 工作 。 我 们 将 在 下 一 节 详 细 讨论 格式 化 程序 。 


ASP.NET Web API 框架 自 带 几 个 内 建 的 模型 绑 定 器 ， 可 以 将 HTTP 消息 中 的 不 同 小 “部 件 ” 
组 合成 相当 复杂 的 模型 。 更 准确 地 说 ， 这 些 实现 也 负责 在 给 模型 “补水 ”之 前 ， 将 字符 串 
转换 为 简单 数据 类 型 ， 如 Timespan, Int, Guid, Decimal 或 带 有 类 型 转换 器 的 其 他 类 型 。 
这 种 内 建 的 模型 绑 定 器 实现 有 : ArrayModelBinder 和 TypeConverterModeLBinder ， 二 者 都 位 
于 System.Web.Http.Model.Binding.Binders 命名 空间 中 。 值 得 一 提 的 是 ， 模 型 绑 定 器 大 多 
数 用 于 “恢复 ”简单 类 型 ， 或 者 为 构建 更 复杂 的 类 型 提供 组 件 。 这 些 内 建 实 现 通常 覆盖 了 
最 常见 的 场景 ， 因 此 ， 如 果 你 要 从 头 编写 一 个 新 的 模型 绑 定 器 ， 最 好 还 是 三 思 而 后 行 。 






































public class Issue 
{ 
public int Id { get; set; } 
public string Name { get; set; } 
public string Description { get; set; } 
} 


Request Uri: http://.../issues/1 
Method: PUT 

Body: 

Name = Mylssue 
Description = My New Issue 


ValueProvider (Id) 


ValueProvider (Description) 


图 13-2: 模型 绑 定 工作 示意 图 


在 图 13-2 中 ， 已 配置 的 值 提 供 程序 首先 将 消息 分 解 为 片段 ， 以 获得 不 同 的 值 ， 例 如 : 查 
询 字符 串 中 的 问题 ID， 以 及 消息 正文 中 的 其 他 字段 。 这 些 字段 使 用 URL 表单 编码 媒体 类 
型 ， 通 过 HTTP PUT 提交 。 选 中 的 模型 绑 定 喜与 值 提供 程序 密切 合作 ， 获 得 初始 化 一 个 新 
的 Issue 实例 所 需 的 数据 。 





























13.3.2 ÉRHET 
值 提供 程序 将 HTTP 消息 不 同 部 分 的 值 聚 合 在 一 起 ， 提 供 一 个 不 变 的 使 用 接口 ， 从 而 形成 
一 个 简单 的 抽象 层 ， 将 模型 绑 定 器 与 消 息 细节 隔离 。 


















































在 其 核心 层 ， 每 个 值 提供 程序 都 实现 了 System.Web.Http.VaLueProviders.IVaLueProvider 
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接口 。 接 口 定义 见 示例 13-7。 


示例 13-7: IValueProvider 接口 定义 


public interface IValueProvider 


{ 
bool ContainsPrefix(string prefix); // <1> 
ValueProviderResult GetValue(string key); // <2> 


} 


Pepe 


第 一 个 方法 ContainsPrefix <1> 返回 一 个 布尔 值 ， 说 明 这 个 值 提供 程序 的 实现 是 否 能 为 以 
参数 prefix 为 前 绥 的 键 提供 值 ， 这 个 前 组 通常 代表 需要 反 序 列 化 的 模型 中 的 一 个 属性 名 。 


第 二 个 方法 GetValue <2> 可 能 是 最 重要 的 ， 这 个 方法 在 HTTP 消息 中 搜索 传人 的 键 ， 返 
回 相 关 的 值 。GetValue 不 直接 返回 原始 字符 串 ， 而 是 返回 一 个 ValueProviderResult 实例 ， 
这 个 实例 提供 方法 ， 以 获得 原始 字符 串 或 者 转换 为 指定 类 型 的 值 。 


你 也 许 希 望 创 建 一 个 新 的 值 提供 程序 ， 或 者 继承 一 个 已 有 的 值 提供 程序 ， 以 解决 新 的 用 
例 ， 例 如 ， 在 请 求 消息 中 使 用 特定 的 命名 约定 搜索 值 ， 或 在 其 他 地 方 (如 定制 cookie) 进 
行 搜索 。 




















示例 13-8 展示 了 值 提供 程序 的 一 个 基本 实现 ， 使 用 一 个 供应 商 前 缀 X- ， 进 行 标 头 搜索 。 





示例 13-8: IValueProvider 实现 
public class HeaderValueProvider : IValueProvider 
{ 
public const string HeaderPrefix = "X-"; 


private HttpControllerContext context; 


public HeaderValueProvider(HttpControllerContext context) // <1> 


{ 
this.context = context; 
} 
public bool ContainsPrefix(string prefix) 
{ 
var contains = context.Request 


.Headers 
.Any(h => h.Key.Contains(HeaderPrefix + prefix)); // <2> 
return contains; 


} 


public ValueProviderResult GetValue(string key) 
{ 
if (!context.Request.Headers.Any(h => h.Key == HeaderPrefix + key)) 
return null; 


var value = context.Request 
.Headers 
.GetValues(HeaderPrefix + key).First(); // <3> 





var stringValue = (value is string) ? (string)value : value.ToString(); // <4> 


return new ValueProviderResult(value, stringValue, 
CultureInfo.CurrentCulture); // <5> 
} 
} 
HeaderValueProvider 的 构造 国 数 参数 为 一 个 HttpControllerContext 实例 ， 这 个 实例 提供 
了 代码 执行 的 上 下 文 以 及 请 求 消息 <1>。 对 于 HTTP 请 求 标 头 中 任何 以 X-prefix 为 前 组 的 
键 ，ContainsPrefix 方法 返回 true, GetValue 方法 返回 键 值 <3>。GetValue 方法 的 返回 值 
Ay ValueProviderResult 实例 <4>， 其 中 包含 值 的 原始 字符 串 <5>。 














IValueProvider 实现 可 以 在 运行 时 通过 一 个 值 提 供 程序 工 三 注入, 值 提供 程序 工厂 是 抽象 类 
System.Web.Http.ValueProvider .ValueProviderFactory 的 派生 类 ， 重 写 J GetValueProvider 
方法 ， 以 返回 IValueProvider 实现 的 实例 。 示 例 13-9 是 对 应 于 HeaderValueProvider 的 值 
提供 程序 工厂 。 





示例 13-9: ValueProviderFactory 实现 


public class HeaderValueProviderFactory : ValueProviderFactory 


{ 


public override IValueProvider GetValueProvider(HttpActionContext actionContext) 


{ 


return new HeaderValueProvider(actionContext.ControllerContext); // <1> 


} 
} 
HeaderValueProviderFactory 以 当前 的 HttpActionContext 为 构造 函数 参数 ， 实 例 化 了 一 
个 新 的 HeaderValueProvider <1>。 我 们 可 以 使 用 爹 局 的 依赖 关系 解析 程序 ， 在 HttpCon 
figuration 对 象 中 注册 这 个 工厂 类 (参见 示例 13-10)。 


出 





示例 13-10: 4 Web 托管 配置 中 注入 HeaderValueProviderFactory 


public static void RegisterValueProvider(HttpConfiguration config) 
{ 
var valueProviderFactories = config.ServiceResolver 
.GetValueProviderFactories().ToList(); 


valueProviderFactories.Insert(@, new HeaderValueProviderFactory()); // <1> 


config.ServiceResolver .SetServices(typeof(System.Web.Http.ValueProviders 
.ValueProviderFactory), 
valueProviderFactories.ToArray()); // <2> 


} 








HeaderValueProviderFactory 被 加 入 到 已 有 的 值 提 供 程序 工厂 列表 的 第 一 位 <1>， 因 此 在 
需要 提供 数据 时 具有 优先 权 ， 之 后 作为 服务 注入 依赖 关系 解析 程序 中 <2>。 








ASP.NET Web API 框架 提供 的 最 重要 的 值 提 供 程 序 是 System.Web.Http.ValueProviders. 
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Providers.QueryStringValueProvider 和 System.Web.Http.ValueProviders.Providers. 
RouteDataValueProvider ， 对 应 的 工厂 类 分 别 为 System.Web.Http.ValueProviders.Providers. 
QueryStringValueProviderFactory 和 System.Web.Http.ValueProviders.Providers. 
RouteDataValueProvider, QueryStringValueProvider 解析 和 提供 查询 字符 串 中 的 值 ， 而 
RouteDataValueProvider 负责 从 路 由 参数 〈 即 路 由 配置 中 路 由 层 定义 的 参数 ) 中 获取 值 。 





13.3.3 ”模型 绑 定 器 

模型 绑 定 器 负责 协调 从 已 配置 的 值 提供 程序 请 求 的 不 同 数据 ,“ 组 装 ” 形 成 一 个 新 的 模型 
实例 的 所 有 操作 。 模 型 绑 定 器 实现 了 System.Web.Http.ModelBinding. IModelBinder 接口 ， 
这 个 接口 只 包含 一 个 方法 BindModel， 所 有 的 关键 代码 都 在 这 个 方法 中 (参见 示例 13-11). 


示例 13-11: IModelBinder 接口 
public interface IModelBinder 


{ 
bool BindModel(HttpActionContext actionContext, ModelBindingContext 
bindingContext); // <1> 

} 











BindModel 方法 有 两 个 参数 <1>: 一 个 是 HttpActionContext 实例 ， 其 中 包含 了 当前 执行 
线程 的 特定 信息 ， 另 一 个 是 ModelBindingContent 实例 ， 表 示 模 型 绑 定 过 程 的 上 下 文 。 
BindModel 方法 返回 一 个 布尔 值 ， 表 明 绑 定 器 是 否 成 功 地 组 装 了 一 个 新 的 模型 实例 。 绑 定 
上 下 文 提 供 两 个 重要 的 属性 : ModelState 和 ModelMetadata, ModelState 是 一 个 属性 包 类 ， 
供 模 型 绑 定 器 存储 绑 定 模型 过 程 的 结果 ， 或 者 过 程 中 可 能 发 生 的 任何 错误 。NModeLMetadata 
提供 了 对 已 发 现 的 模型 元 数据 的 访问 ， 例 如 : 可 用 属性 ， 或 者 执行 数据 验证 的 任何 组 件 模 
型 属性 。IModelBinder 接口 看 似 非常 简单 ， 其 中 却 隐 藏 了 复杂 的 逻辑 ， 实 现 模型 绑 定 器 ， 
并 在 运行 时 提供 正确 的 行为 。 因 此 ， 我 们 接 下 来 要 详细 描述 ， 一 个 IModelBinder 实现 要 执 
行 的 所 有 步骤 。 


(1) 代码 使 用 从 BindModel 的 绑 定 上 下 文 参 数 中 得 到 的 值 提 供 程序 ， 举 试 获得 组 装 新 模型 需 
要 的 所 有 值 。 虽 然 绑 定 上 下 文 只 提供 对 一 个 值 提供 程序 的 访问 ， 但 这 个 实例 通常 代表 一 
个 内 建 的 值 提供 程序 CompositeValueProvider， 这 个 值 提 供 程 序 实现 了 IValueProvider 
接口 ， 而 其 内 部 将 方法 调用 委托 给 所 有 已 配置 的 值 提 供 程序 。 

(2) 代码 创建 一 个 模型 ， 并 使 用 从 值 提 供 程序 获得 所 有 值 进行 初始 化 。 如 果 模 型 初始 化 过 程 
中 发 生 了 错误 ， 那 么 代码 将 异常 保存 在 绑 定 上 下 文 的 Modelstate 属性 中 。 

(3) 代码 将 模型 保存 在 绑 定 上 下 文中 。 




























































































示例 13-12 中 的 模型 绑 定 器 实现 ， 创 建 了 本 章 之 前 讨论 过 的 Issue 模型 类 。 
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示例 13-12: IssueModelBinder 实现 


public class IssueModelBinder : IModelBinder 


{ 


public bool BindModel(HttpActionContext actionContext, ModelBindingContext 
bindingContext) 


{ 


} 


var model = (Issue)bindingContext.Model ?? new Issue(); 


var hasPrefix = bindingContext.ValueProvider 
.ContainsPrefix(bindingContext.ModelNane) ; 


var searchPrefix = (hasPrefix) ? bindingContext.ModelName + "." : ""; 
int id = 
if(int.TryParse(GetValue(bindingContext, searchPrefix, "Id"), out id) 
{ 

model.Id = id; // <1> 
} 


model.Name = GetValue(bindingContext, searchPrefix, "Name"); // <2> 
model.Description = GetValue(bindingContext, searchPrefix, "Description");// <3> 


bindingContext.Model = model; 


return true; 


private string GetValue(ModelBindingContext context, string prefix, string key) 


i 


} 


} 


var result = context.ValueProvider .GetValue(prefix + key); // <4> 
return result == null ? null : result.AttemptedValue; 


这 个 实现 使 用 了 绑 定 上 下 文中 的 值 提 供 程序 <1> 进行 数据 请 求 ， 随 后 在 <2>、<3> 和 <4> 
中 将 这 些 数据 绑 定 到 模型 的 属性 。 你 在 实际 的 应 用 程序 中 可 能 不 会 这 么 做 ， 但 是 这 个 实现 
简单 演示 了 IModelBinder 实现 的 大 致 内 容 。 





在 运 





Provider, 























SÍT, FEAA Te ae HY SC EW tee Ze a ch ie a ce ee hE ERENT VET ACA ATE A BEB 
定 器 提供 程序 是 一 个 工厂 类 ， 继 承 了 基 类 System. Web.Http.ModelBinding.ModelBinder 











并 实现 GetBinder 方法 ， 返 回 一 个 新 的 模型 绑 定 程 序 实例 (参见 示例 13-13 ) 。 





示例 13-13: 返回 IssueModelBinder 实例 的 ModelBinderImplementation 实现 


public class IssueModelBinderProvider : ModelBinderProvider 


{ 


public override IModelBinder GetBinder(HttpActionContext actionContext, 
ModelBindingContext bindingContext) 


{ 
} 


} 


return new IssueModelBinder(); 
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你 可 以 使 用 HttpConfiguration 对 象 中 的 依赖 关系 解析 程序 注册 这 个 提供 程序 ， 或 者 给 模 
型 类 添加 一 个 System.Web.Http.ModelBinding.ModelBinderAttribute 属性 (参见 示例 13-14 


和 示例 13-15)。 


示例 13-14: 带 有 ModelBinderAttribute 属性 的 模型 类 


[ModelBinder (typeof(IssueModelBinderProvider))] 
public class Issue 


{ 
public int Id { get; set; } 
public string Name { get; set; } 
public string Description { get; set; } 


} 


示例 13-15: 带 有 ModelBinderAttribute 属性 的 参数 
public void Post([ModelBinder(typeof(IssueModelBinderProvider))]Issue issue) 


{ 
I 


关于 ModelBinderAttribute 有 一 个 有 趣 的 事实 : ModelBinderAttribute 派生 自 之 前 讨论 
过 的 ParameterBindingAttribute 属性 。ParameterBindingAttribute 用 于 通过 声明 将 一 
个 HttpParamterBinding 实例 附 到 一 个 参数 上 。ModelBinderAttribute 初始 化 一 个 新 的 
ModelBindingParameterBinder 实例 ， 该 实例 内 部 使 用 ModelBinderProvider 为 参数 (在 我 
们 的 示例 中 是 IssueModelBinderProvider ) 。 





13.3.4 只 对 URI 进 行 模型 绑 定 


ASP.NET Web API 框 架 还 提供 另外 一 个 属性 FromUriAttribute， 这 个 属性 派生 自 


ModelBinderAttribute， 强 制 运行 时 只 对 URL 中 可 用 的 数据 执行 绑 定 ， 可 以 用 于 将 URL 中 
找到 的 值 绑 定 到 模型 类 的 属性 ， 因 为 在 默认 情况 下 框架 只 将 URL 中 的 数据 绑 定 到 简单 类 型 。 














示例 13-16 展示 了 查询 字符 串 变量 Lang 和 Filter 如 何 自 动 映射 到 IssueFilters 模型 上 的 
同名 属性 。 


示例 13-16: 查询 字符 串 变量 的 模型 绑 定 


// urL 示例 : http://../Issues?Lang=en&Filter=2345 


public class IssueFilters 


{ 
public string Lang { get; set; } 
public string Filter { get; set; } 


} 


public IEnumerable<Issue> Get([FromUri]IssueFilters) 


{ 
// 操作 实现 代码 





13.3.5 FormatterParameterBinder Sil 


ASP.NET Web API 中 引入 了 格式 化 程序 ， 以 更 好 地 支持 使 用 媒体 类 型 时 的 内 容 协商 。 
FormatterParameterBinder 实现 依赖 于 格式 化 程序 。 在 ASP.NET MVC 中 , 只 有 HTML (text/ 
html) 和 JSON (application/json) 是 第 一 类 媒体 类 型 ， 在 整个 栈 中 得 到 支持 。 而 且 ， 
ASP.NET MVC 中 没有 支持 内 容 协 商 的 一 致 模型 。 你 可 以 提供 定制 的 AxtionResult 实现 ， 
为 响应 消息 支持 不 同 的 媒体 类 型 ， 但 是 框架 没有 明确 规定 如 何 引 入 和 处 理 新 的 媒体 类 型 。 
开发 者 通常 会 利用 模型 绑 定 基础 结构 ， 使 用 新 的 模型 绑 定 器 或 者 值 提 供 程 序 ， 来 解决 这 个 
问题 。 












































幸好 ，ASP.NET Web API 引入 了 格式 化 程序 的 概念 ， 解 决 了 ASP.NET MVC 中 的 不 一 致癌 
题 。 现 在 ， 格 式 化 程序 提供 单一 的 入 口 点 ， 使 用 媒体 类 型 表达 的 格式 ， 进 行 模型 的 序列 化 
和 反 序 列 化 ， 从 而 统一 了 序列 化 问题 的 处 理 。 内 容 协 商 算 法 将 决定 对 于 给 定 的 消息 使 用 哪 
种 格式 化 程序 。 


每 个 格式 化 程序 都 派生 自 基 类 MediaTypeFormatter (参见 示例 13-17) ， 并 重 写 CanReadType 
和 ReadFromStreamAsync 方法 以 支持 反 序 列 化 ， 对 CanWriteType 和 WriteToStreamAsync 方 
法 进行 重 写 ， 以 根据 媒体 类 型 的 语义 和 格式 进行 模型 的 序列 化 。 








示例 13-17: MediaTypeFormatter 类 定义 


public abstract class MediaTypeFormatter 

i public Collection<Encoding> SupportedEncodings { get; } 
public Collection<MediaTypeHeaderValue> SupportedMediaTypes { get; } 
public Collection<MediaTypeMapping> MediaTypeMappings { get; } 
public abstract bool CanReadType(Type type); 


public abstract bool CanWriteType(Type type); 


public virtual Task<object> ReadFromStreamAsync(Type type, Stream readStream, 
HttpContent content, IFormatterLogger formatterLogger ); 


public virtual Task WriteToStreamAsync(Type type, object value, 
Stream writeStream, HttpContent content, TransportContext transportContext) ; 


} 
下 面 罗 列 了 MediaFormatter 类 的 主要 特征 。 


e CanReadType 和 CanWriteType 方法 的 参数 是 一 个 类 型 ， 必 须 返 回 一 个 值 ， 说 明 这 个 格式 
化 程序 是 否 能 够 从 代表 消息 正文 的 流 中 读 取 ,或 者 回流 中 写 入 该 类 型 的 一 个 对 象 。 例 如 ， 
一 个 格式 化 程序 可 能 知道 如 何 写 入 一 个 类 型 ， 但 是 不 知道 如 何 从 流 中 读 取 该 类 型 。 
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e SupportedMediaTypes 集合 包含 了 这 个 格式 化 程序 支持 的 媒体 类 型 列表 (例如 : text/ 
html)。 这 个 列表 通常 在 格式 化 程序 类 的 构造 函数 中 初始 化 。 运 行 时 必须 在 内 容 协 商 握 
手中 ， 基 于 CanReadType 或 CanWriteType 方法 的 返回 值 ， 以 及 格式 化 程序 支持 的 媒体 类 
型 , 决定 使 用 哪个 格式 化 程序 。 值 得 一 提 的 是 , 当 Content-Type 标 头 设 为 multipart 时 ， 
请 求 消息 可 以 混合 使 用 不 同 的 媒体 类 型 ， 由 消息 的 每 个 部 分 定义 自己 的 媒体 类 型 。 运 行 
时 可 以 为 消息 中 存在 的 所 有 媒体 类 型 选择 一 个 或 多 个 格式 化 程序 ， 处 理 混合 媒体 类 型 的 
消息 。 

。 对 于 读 写 操作 ，MediaTypeFormatter 遵循 任务 并 行 库 (Task Parallel Library, TPL) 编程 
模型 。 大 部 分 的 实现 只 涉及 序列 化 操作 ， 因 此 仍 将 同步 执行 。 

。 格式 化 程序 可 以 使 用 MediaTypeMappings 集合 ， 定 义 如 何 寻 找 与 一 个 请 求 消 息 相 关 的 媒 
体 类 型 (如 查询 字符 串 和 HTTP 标 头 )。 例 如 ， 一 个 客户 端 应 用 程序 可 能 在 查询 字符 串 
中 发 送 预 期 的 响应 媒体 格式 。 


ASP.NET Web API 框架 提供 一 组 直接 可 用 的 格式 化 程序 ， 可 以 处 理 大 部 分 的 常用 媒体 类 型 ， 
例如 : 表单 编码 数据 (FormUrlEncodedMediaTypeFormatter), JSON (JsonMediaTypeFormatter ) 
或 者 XML (XmLMediaTypeFormatter)。 对 于 其 他 的 媒体 类 型 ， 你 需要 实现 自己 的 格式 化 程 
序 ， 或 者 使 用 开源 社区 提供 的 诸多 实现 中 的 一 个 。 













































































JsonMediaTypeFormatter 和 XmlMediaTypeFormatter 


值得 一 提 的 是 ， 目 前 JsonMediaTypeFormatter 在 内 部 使 用 JsonNET 库 ， 进 行 
JSON 有 效 载荷 的 序列 化 / 反 序 列 化 ,XmlLMediaTypeFormatter 使 用 .NET 框架 中 的 
DataContractSerializer 或 XmlSerializer 类 。XmLMediaTypeFormatter 提供 一 个 布尔 型 的 
属性 UserXmlSerializer， 用 于 设置 是 否 使 用 XmlSerializer X, UserXmlSerializer 的 默 
认 值 为 faLse。 你 可 以 扩展 这 些 类 ， 使 用 自己 偏好 的 库 ， 进 行 XML A JSON 的 序列 化 。 











现在 ， 我 们 要 讨论 MediaTypeFormatter 的 一 个 实现 ， 将 一 个 模型 进行 序列 化 ， 成 为 RSS 或 
ATOM 源 的 一 部 分 (参见 示例 13-18). 


示例 13-18: MediaTypeFormatter 实现 


public class SyndicationMediaTypeFormatter : MediaTypeFormatter 


public const string Atom = "“application/atom+xml"; 
public const string Rss = "application/rss+xmL"; 


public SyndicationMediaTypeFormatter () 
: base() 

{ 
this.SupportedMediaTypes.Add(new MediaTypeHeaderValue(Atom)); // <1> 
this.SupportedMediaTypes.Add(new MediaTypeHeaderValue(Rss)); 
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public override bool CanReadType(Type type) 
{ 


return false; 


} 


public override bool CanWriteType(Type type) 
{ 


return true; // <2> 


} 


public override Task WriteToStreamAsync(Type type, object value, Stream 
writeStream, HttpContent content, TransportContext transportContext) // <3> 
{ 
var tsc = new TaskCompletionSource<AsyncVoid>(); // <4> 
tsc.SetResult(default(AsyncVoid) ); 


var items = new List<SyndicationItem>(); 


if (value is IEnumerable) 
{ 
foreach (var model in (IEnumerable)value) 
{ 
var item = MapToItem(model); 
items .Add(item); 
} 
} 
else 
{ 
var item = MapToItem(value) ; 
items.Add(item) ; 


} 
var feed = new SyndicationFeed(items) ; 


SyndicationFeedFormatter formatter = null; 
if (content.Headers.ContentType.MediaType == Atom) 


{ 
formatter = new Atom1@FeedFormatter (feed); 
} 
else if (content.Headers.ContentType.MediaType == Rss) 
{ 
formatter = new Rss20FeedFormatter (feed); 
} 
else 
{ 
throw new Exception("Not supported media type"); 
} 


using (var writer = XmlWriter.Create(writeStream) ) 


{ 


formatter .WriteTo(writer); 


writer.Flush(); 
writer.Close(); 
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} 


return tsc.Task; // <5> 


} 


protected SyndicationItem MapToItem(object model) // <6> 
{ 


var item = new SyndicationItem(); 
item. ELementExtensions.Add(model); 


return item; 


} 


private struct AsyncVoid 
{ 
} 

} 


这 个 实现 只 知道 如 何 根据 Atom 和 RSS 媒体 类 型 定义 进行 模型 的 序列 化 ， 因 此 在 构造 函 
数 中 明确 声明 了 这 两 个 类 型 <1>。 re tn 的 CanWrite 方法 返回 
true， 说 明 这 个 实现 只 支持 写 操作 <2>。 











WriteToStreamAsync 方法 的 实现 <3> 主要 依赖 WCF Web 编程 模型 中 的 联合 (syndication) 
类 ， 将 模型 序列 化 为 Atom 或 RSS 源 。 这 个 编程 模型 提供 了 构建 一 个 联合 源 (syndication 
feed) 和 所 有 相关 条 目的 类 ， 还 提供 格式 化 程序 类 ， 将 这 些 源 和 条 目 转化 为 常见 的 联合 源 
格式 ， 例 如 : Atom 或 RSS。 


我 们 前 面 提 到 ，WriteToStreamAsync 和 ReadFromStreamAsync 方法 使 用 新 的 任务 并 行 库 进行 
异步 操作 。 这 两 个 方法 都 返回 一 个 Task 实例 ， 其 中 封装 了 异步 操作 。 但 是 ， 在 大 多 数 时 
候 ， 序 列 化 操作 是 安全 的 ， 可 以 同步 完成 。 实 际 上 ，.NET 框架 中 的 很 多 序列 化 程序 类 都 
执行 同步 操作 。 最 简单 的 做 法 是 ， 使 用 Task.Factory.StartNew 方法 ， 为 所 有 的 序列 化 工 
作 创 建 一 个 新 任务 ， 但 是 这 种 做 法 会 产生 一 些 副 作用 。 在 调用 startNew 方法 之 后 ， 新 任务 
计划 执行 ， 可 能 会 产生 一 个 线程 上 下 文 切换 ， 对 性 能 产生 影响 。 在 这 种 情况 下， 诀窍 是 使 
用 一 个 TaskCompletionSource<4>, TaskCompletionSource 标记 为 complete， 因 而 此 后 的 所 
有 工作 都 会 同步 完成 ， 返 回 与 TaskCompletingSource 关联 的 最 终 任务 <5>。MapToIten 方法 
<6> 只 是 简单 地 将 模型 实例 用 做 一 个 联合 源 项 (syndication item) 的 内 容 。 




















同步 格式 化 程序 


大 多 数 的 格式 化 程序 都 是 同步 的 ， 使 用 一 个 TaskCompletionSource 实例 返回 完成 的 任 
务 。 但 是 ， 如 果 你 希望 使 实现 更 为 简单 ， 有 一 个 基 类 BuffteredMediaFormatter 可 以 在 
内 部 完成 所 有 这 些 工 作 。 这 个 基 类 提供 两 个 可 以 在 实现 中 重 写 的 方法 : SaveToStream 
和 ReadFromStream， 这 两 个 方法 分 别 是 SaveToStreamAsync 和 ReadFromStreamAsync 的 
同步 版 本 。 
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在 格式 化 程序 中 ， 我 们 可 能 希望 支持 的 另 一 个 功能 是 ， 使 用 Accept 标 头 之 外 的 信息 源 进 
行内 容 协商 。 如 今 ， 在 没有 正确 实现 HTTP 客户 栈 的 客户 端 〈 例 如 一 些 旧 版 本 移动 设备 的 
浏览 器 ) 中 ， 我 们 经 常会 需要 这 种 功能 。 在 这 种 情况 下 ， 一 个 客户 端 可 能 希望 在 查询 字符 
串 中 提供 可 接受 的 媒体 类 型 ， 例 如 :http://.../Issues?format=atom。MediaTypeFormatter 
通过 MediaMappings 属性 提供 对 这 种 场景 的 支持 ，MediaMappings 属性 是 MediaMapping 实例 
的 集合 ，MediaMapping 表明 了 可 以 找到 媒体 类 型 的 位 置 ， 例 如 : 查询 字符 串 、 标 头 或 URI 
Be. ASP.NET Web API 框架 提供 了 抽象 类 MediaMapping 的 几 个 具体 实现 ， 以 解决 最 为 常 
见 的 情况 。 以 下 是 这 些 映 射 类 的 简单 介绍 。 

















e QueryStringMapping 
可 用 于 将 请 求 的 媒体 类 型 映射 到 查询 字符 串 变 量 。 例 如 ，URL http://localhost/issues? 
format=atom 中 的 格式 变量 会 映射 到 媒体 类 型 atom。 


e UriPathExtensionMapping 


可 用 于 将 URI 中 的 路 径 映 射 到 媒体 类 型 。 例 如 ，http:/ localhost/issues.atom 中 的 路 
径 .atom 会 映射 到 媒体 类 型 atom。 


e RequestHeaderMapping 
将 请 求 标 头 映射 到 媒体 类 型 。 如 果 你 不 想 使 用 任何 标准 HTTP 请 求 标 头 ， 就 可 以 使 用 这 
个 类 。 


媒体 类 型 映射 通过 格式 化 程序 的 构造 函数 注入 到 格式 化 程序 中 。 示 例 13-19 展示 了 如 何 
修改 格式 化 程序 的 构造 函数 ， 使 用 QueryStringMapping 实例 ， 在 查询 字符 串 中 搜索 媒体 
类 型 。 


示例 13-19: 从 查询 字符 串 进行 媒体 类 型 映射 
public const string Atom = "“application/atom+xml"; 
public const string Rss = "application/rss+xmL"; 





public SyndicationMediaTypeFormatter () 
: base() 

{ 
this.SupportedMediaTypes.Add(new MediaTypeHeaderVaLue(Atom) ); 
this.SupportedMediaTypes.Add(new MediaTypeHeaderVaLue(Rss) ); 


this.MediaTypeMappings 
.Add(new QueryStringMapping("format", "atom", 
new MediaTypeHeaderValue(Atom))); // <1> 
} 


如 果 格 式 化 程序 找到 一 个 查询 字符 串 变 量 format， 变 量 值 为 atom， 就 将 其 映射 到 媒体 类 型 


Atom (application/atom+xml) <I>, 
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13.3.6 ”HttpParameterBinding 的 默认 选择 


在 默认 情况 下 ， 模 型 绑 定 基础 结构 会 尝试 使 用 FormatterParameterBinder 进行 复杂 类 型 参 
数 的 绑 定 ， 对 简单 的 NET 类 型 则 使 用 ModelBindingParameterBinder。 在 有 多 个 复杂 类 型 
参数 的 情况 下 ， 除 非 你 使 用 Fromuriattribute 属性 ， 明 确 指定 一 个 参数 必须 从 URL 中 进 
FTA, H FromBodyAttribute 属性 指定 参数 必须 从 正文 中 绑 定 ， 否 则 绑 定 将 会 失败 。 
你 可 以 使 用 FromBodyAttribute， 对 指定 的 参数 强制 使 用 FormatterParameterBinder。 如 果 
一 个 操作 包含 多 个 复杂 参数 ， 其 中 只 有 一 个 参数 可 以 通过 使 用 FromBodyAttribute， 从 请 求 
正文 中 读 取 。 否 则 ， 运 行 时 将 会 抛 出 异常 。 


13.4 ”模型 验证 


模型 验证 是 带 有 模型 绑 定 基础 结构 的 Web API 提供 的 另 一 个 功能 。 你 可 以 使 用 这 个 功能 强 
制 执行 业务 规则 ， 或 者 确保 客户 端 发 送 数据 的 正确 性 。 模 型 验证 在 模型 绑 定时 在 单一 位 置 
执行 ， 这 种 集中 性 使 得 代码 更 易 维 护 和 测试 。 


模型 验证 的 另 一 个 重要 功能 是 ， 将 客户 端 发 送 数据 的 任何 可 能 错误 通知 客户 端 ， 提 供 更 正 
这 些 错 误 的 机 会 。 在 实践 中 ， 如 果 一 个 Web API 没有 实现 这 个 功能 ， 开 发 者 会 停止 在 应 用 
程序 中 使 用 这 个 API。 


和 模型 绑 定 基础 结构 的 其 他 部 分 一 样 ，ASP.NET Web API 中 的 模型 验证 也 是 完全 可 扩展 
的 。 框 架 自 带 一 个 通用 的 验证 程序 ， 使 用 属性 进行 模型 验证 。 这 个 验证 程序 可 以 满足 大 部 
分 情况 的 需求 ， 并 重用 了 System.ComponentModeL.DataAnnotations 命名 空间 中 的 数据 标 
记 属 性 。System.ComponentModel.DataAnnotations 命名 空间 中 提供 几 种 验证 属性 ， 例 如 ; 
Required 标记 属性 为 必需 的 ，RegularExpression 使 用 正则 表达 式 验 证 属性 值 。 你 也 可 以 自 
己 创建 定制 的 数据 标记 属性 ， 以 满足 内 建 属性 没有 覆盖 到 的 需求 。 



























































13.4.1 ”将 数据 标记 属性 用 于 模型 
假设 我 们 希望 对 问题 模型 进行 一 些 验证 。 我 们 可 以 首先 使 用 数据 标记 属性 修饰 模型 ， 无 需 
编写 很 多 代码 就 可 以 执行 通常 的 验证 ， 更 重要 的 是 ， 使 用 数据 标记 属性 不 需要 重复 编码 。 
示例 13-20 展示 了 带 有 一 些 数据 标记 属性 的 问题 模型 。 


示例 13-20: 带 有 数据 标记 属性 的 问题 模型 
public class Issue 
{ 
[DisplayName("Issue Id") ] 
[Required(ErrorMessage = "The issue id is required") ] 
[Range(1, 1000, ErrorMessage = "The unit price must be between {1} and {2}")] 
public int Id { get; set; } 
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[DisplayName( "Issue Name") ] 
[Required(ErrorMessage = "The issue name is required") ] 
public string Name { get; set; } 


[DisplayName("Issue Description") ] 
[Required(ErrorMessage = "The issue description is required") ] 
public string Description { get; set; } 


} 


这 个 模型 中 的 所 有 属性 都 带 有 标签 ， 明 确 声 明了 各 自 的 用 途 。 一 些 属性 ， 例 如 : Name 和 
Description, 标记 为 required; Id 标记 为 需要 指定 范围 内 的 值 。DisplayName 属性 不 用 于 














数据 验证 ， 但 是 会 影响 输出 消息 的 显示 。 


13.4.2 ”查询 验证 结果 





一 旦 模型 绑 定 基础 结构 基于 模型 上 定义 的 属性 ， 完 成 了 模型 的 验证 ， 验 证 结果 就 可 以 由 控 


制 器 使 用 ， 或 者 以 更 为 集中 的 方式 ， 由 筛选 器 使 用 。 


要 检查 模型 是 
ITRE (参见 示例 13-21 ) 。 


示例 13-21: 在 操作 实现 中 检查 验证 结果 
public class ValidationError 


{ 
public string Name { get; set; } 
public string Message { get; set; } 


} 





public class IssueController : ApiController 
{ 
public HttpResponseMessage Post(Issue product) 
{ 
if(!this.ModelState. IsValid) 
{ 
var errors = this.ModelState // <1> 
-Where(e => e.Value.Errors.Count > 0) 
.Select(e => new ValidationError // <2> 
{ 
Name = e.Key, 
Message = e.Value.Errors.First().ErrorMessage 


}).ToArray(); 


var response = new HttpResponseMessage(HttpStatusCode.BadRequest) ; 


response.Content = new ObjectContent<ValidationError[ ]>(errors, 
new JsonMediaTypeFormatter()); 


return response; 


} 
// 操作 代码 


否 成 功 绑 定 ， 所 有 验证 结果 是 否 通过 ， 最 简单 的 方法 是 在 操作 实现 中 加 入 几 
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} 
} 


正如 示例 13-21 所 示 ， 控 制 器 操作 的 Modelstate 属性 <1> 可 以 得 到 所 有 的 验证 结果 。 在 示 
例 中 ,操作 方法 只 是 简单 地 将 所 有 的 验证 错误 转换 为 一 个 新 的 模型 类 ValidationError<2>， 
我 们 可 以 将 这 个 类 序列 化 为 JSON 格式 的 响应 正文 ， 加 上 一 个 Bad Request 状态 码 返 回 








o 





这 个 示例 中 的 代码 很 通用 ， 你 可 能 希望 在 多 个 操作 中 重用 ， 因 此 也 许 最 好 的 方法 是 把 这 些 
通用 代码 移 到 一 个 定制 的 筛选 器 中 。 示 例 13-22 中 的 筛选 右 包 含 了 同样 的 检查 代码 。 





示例 13-22: 执行 验证 的 ActionFilterAttribute 实现 
public class ValidationActionFilter : ActionFilterAttribute 
{ 
public override void OnActionExecuting(HttpActionContext actionContext) 
{ 
if (!actionContext.ModelState. IsValid) 
{ 
var errors = this.ModelState 
.Where(e => e.Value.Errors.Count > 0) 
.Select(e => new ValidationError 


{ 

Name = e.Key, 

Message = e.Value.Errors.First().ErrorMessage 
}).ToArray(); 


var response = new HttpResponseMessage(HttpStatusCode.BadRequest) ; 
response.Content = new ObjectContent<ValidationError[ ]>(errors, 
new JsonMediaTypeFormatter()); 


actionContext.Response = response; 


} 
} 


你 可 以 看 到 ， 这 个 筛选 器 的 实现 也 非常 简单 。 当 筛选 器 检测 到 无 效 模型 ， 执 行 管道 就 会 自 
apt, Te) API 使 用 者 发 送 一 个 包含 验证 错误 信息 的 新 响应 。 例 如 ， 如 果 我 们 发 送 了 一 个 
包含 空 产品 名 和 无 效 单价 的 消息 ， 就 会 得 到 示例 13-23 中 的 响应 。 


示例 13-23: 无 效 请 求 消息 和 对 应 的 响应 消息 


Request Message in JSON 


POST http://../Isssues HTTP/1.1 
Content-Type: application/json 


{ 
Ids: iy 
"Name":"", 
"Description": "My issue" 





Response Message 


HTTP/1.1 400 Bad Request 
Content-Type: text/plain; charset=utf-8 


[{ 
"Message": "The Issue Name is required.", 
"Name": "Name" 


}] 


13.5 ”小结 


模型 绑 定 基础 结构 是 HITP 消 息 和 模型 对 象 实例 之 间 的 映射 层 主要 依赖 
HttpParameterBinding 组 件 ， 将 参数 绑 定 到 HTTP 消息 的 各 个 部 分 ， 例 如 : 标 头 、 查 询 字 
符 串 或 正文 文本 。ASP.NET Web API 框架 自身 提供 了 HttpParameterBinding 的 两 个 实现 : 
ModelBindingParameterBinder 和 FormatterParameterBinder， 前 者 使 用 借用 自 ASP.NET 
MVC 中 的 传统 绑 定 机 制 〈 模 型 由 HITP 消息 中 的 片段 组 成 )， 后 者 使 用 格式 化 程序 将 媒体 
类 型 格式 转换 成 模型 。 


ModelBindingParameterBinder 使 用 了 IValueProvider 实例 ， 从 HTTP 消息 的 不 同 部 分 收集 
数据 ， 并 使 用 IModelBinder 实例 将 所 有 数据 组 合 形成 单个 模型 。 





FormatterParameterBinder 是 内 容 协 商 的 基础 组 成 部 分 ， 为 FormatterParameterBinder 
理解 如 何 使 用 格式 化 程序 ， 将 一 个 带 有 语义 规则 和 指定 媒体 类 型 的 HTTP 消息 正文 转换 成 


一 个 模型 。 

















格式 化 程序 派生 自 基 类 MediaTypeFormatter， 通 常 处 理 单个 媒体 类 型 。 除 了 进行 参数 绑 定 ， 
模型 绑 定 基础 结构 还 提供 一 个 扩展 点 ， 用 于 在 模型 反 序列 化 后 对 其 进行 验证 。 默 认 情 况 
下 ， 模 型 验证 的 规则 由 数据 标记 属性 定义 。 
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第 14 章 


HttpClient 





工 欲 善 其 事 ， 必 先 利 其 器 。 
本 章 深入 探讨 第 10 章 中 介绍 的 System.Net Http 程序 库 中 的 HttpClient 类 。 


2009 年 初 ，HttpCLient 与 REST Starter Kit (RSK) 绑 定 在 一 起 ， 首 次 出 现在 CodePlex 
上 。HttpClient 引入 了 一 些 概念 ， 例 如 : 请 求 / 响 应 管道 ， 与 请 求 /响应 以 及 强 类 型 标 头 
不 同 的 HTTP 有 效 载荷 抽象 。 虽 然 NET 框架 4.0 BA T RSK 的 很 多 内 容 ， 但 是 没有 包含 
HttpClient。 当 2010 年 Web API 项 目 启动 时 ， 项 目的 核心 任务 之 一 就 是 重 写 HttpClient。 











14.1 HttpClient 类 


简单 的 事情 应 该 简单 实现 ，HttpCLient 坚守 这 一 原则 。 请 看 下 面 的 代码 : 





var client = new HttpClient(); 
string rfc2616Text = 
await client.GetStringAsync("http://www.ietf.org/rfc/rfc2616.txt"); 


这 个 示例 初始 化 了 一 个 新 的 HttpCLient 对 象 ， 发 起 一 个 HTTP GET 请 求 ， 并 将 啊 应 的 内 容 
转换 成 .NET 字符 串 。 

这 段 看 似 寻 常 的 代码 为 我 们 提供 了 足够 的 背景 ， 讨 论 与 HttpCLient 类 的 使 用 相关 的 一 系列 
问题 。 
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14.1.1 生存 周期 

虽然 HttpClient 间接 实现 了 IDisposal 接口 ， 但 是 我 们 不 推荐 在 每 个 请 求 后 释放 
HttpClient。 这 个 HttpCLient 对 象 应 该 用 于 你 的 应 用 程序 所 有 的 HTTP 请求。 如 果 多 个 
请 求 使 用 同一 个 HttpClient 对 象 ， 那 么 我 们 就 可 以 在 这 个 对 象 中 设置 DefaultRequest 
Headers， 以 免 像 使 用 HttpWebRequest 时 一 样 ， 对 每 个 请 求 都 进行 像 CredentiaLCache 和 
CookieContainer 这 样 的 设置 。 


























14.1.2 封装 类 

有 趣 的 是 ，HttpCLient 自身 并 不 执行 发 起 HTTP 请 求 的 具体 工作 ， 而 是 将 这 些 工作 交 给 一 
个 派生 自 HttpMessageHandler 的 聚合 对 象 。HttpCLient 的 默认 构造 函数 负责 初始 化 聚合 对 
象 。 你 也 可 以 在 构造 函数 中 传人 一 个 聚合 对 象 ， 代 码 如 下 所 示 ; 


var client = new HttpClient((HttpMessageHandler) new HttpClientHandler()); 





HttpClientHandler 在 内 部 使 用 System.Net 的 HttpWebRequest 和 HttpWebResponse 类 。 这 种 
设计 提供 了 最 优 的 结果 。 今 天 ， 我 们 获得 了 新 接口 ， 访 问 一 个 已 证 明 的 HTTP 栈 ， 明 天 ， 
我 们 可 以 将 HttpCLientHandtLer 替换 为 某 些 改进 过 的 HTTP 内 部 实现 ， 而 应 用 程序 的 接口 
不 会 发 生变 化 。HttpClientHandler 的 实现 使 用 了 System. Net 程序 库 各 个 版 本 中 通用 的 部 
分 ， 可 以 在 多 个 平台 上 使 用 ， 例 如 : WinRT 和 Windows Phone。 由 于 这 种 设计 选择 ， 我 们 
无 法 直接 使 用 一 些 功能 ， 例 如 : 客户 端 缓 存 、 管 道 和 客户 端 认 证 ， 因 为 这 些 功 能 都 依赖 桌 
面 操作 系统 。 要 使 用 这 些 功能 ， 你 需要 使 用 如 下 代码 : 
var handler = new WebRequestHandler { 
AuthenticationLevel = AuthenticationLevel.MutualAuthRequired, 


CachePolicy = new RequestCachePolicy(RequestCacheLevel.Default) 
}; 


var httpClient = new HttpClient(handler); 


WebRequestHandler 类 派生 自 HttpCLientHandLter ， 但 位 于 另 一 个 单独 的 程序 集 System.Net. 
Http.WebRequest, 


HttpClient 实现 IDisposable 接口 是 为 了 释放 HttpMessageHandler, HttpMessageHandler [iti 
之 尝试 关闭 底层 的 TCP/IP 连接 。 这 意味 着 ， 创 建 一 个 新 的 HttpClient 并 发 起 新 的 请 求 ， 
需要 创建 一 个 新 的 底层 端口 连接 ， 如 果 只 是 为 了 发 起 一 个 请 求 ， 这 种 操作 的 代价 可 谓 非常 


=e 


i=] 
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有 一 点 要 注意 ， 如 采 你 在 HttpClient 外 部 实例 化 一 个 HttpMessageHandler ， 并 将 这 个 处 理 
程序 传递 给 HttpCLient 的 构造 程序 ， 那 么 释放 HttpClient 就 会 导致 这 个 处 理 程序 无 法 使 
用 。 如 果 配 置 这 个 处 理 程序 相当 复杂 ， 那 么 你 可 能 会 希望 能 够 在 多 个 Httpclient 实例 中 重 
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用 这 个 处 理 程序 。 幸 好 ，ASP.NET Web API 添加 了 一 个 新 的 HttpClient 构造 国 数 ， 以 支 
持 处 理 程序 的 重用 : 








var handler = HttpHandlerFactory.CreateExpensiveHandler(}; 
var httpClient = new HttpClient(handler, disposeHandler: false); 

















如 果 你 在 构造 函数 中 告诉 HttpClient 不 要 释放 HttpMessageHandler, HE ATLA ES 
HttpClient 实例 中 重用 这 个 消息 处 理 程序 。 





14.1.3 ”多 个 实例 
一 旦 发 出 第 一 个 请 求 ，HttpClient 的 某 些 属性 就 无 法 再 修改 ， 这 可 能 导致 你 想 要 创建 多 个 
HttpClient 实例 。 这 些 属性 有 : 




















public Uri BaseAddress 
public TimeSpan Timeout 
public long MaxResponseContentBufferSize 


14.1.4 BERS 
HttpClient 类 是 线程 安全 的 ， 可 以 很 愉快 地 管理 多 个 并 行 的 HTTP 请 求 。 如 果 前 面 列 出 的 
三 个 属性 在 请 求 处 理 过 程 中 发 生 了 变化 ， 那 么 可 能 导致 难以 定位 的 错误 。 



































这 些 属 性 比较 容易 理解 ， 但 是 我 们 需要 强调 一 下 MaxResponseContentBufferSize。 
MaxResponseContentBufferSize 属性 的 数据 类 型 是 Long， 但 是 默认 值 和 最 大 值 仅 为 Int32. 
MaxValue， 这 个 最 大 值 对 大 多 数 情况 都 是 足够 的 。 不 要 担心 ， 尽管 这 个 属性 值 最 大 可 以 设 
置 到 4 GB， 但 是 HttpClient 只 会 分 配 HTTP 有 效 载 答 缓存 所 需 的 内 存 ， 不 会 过 多 分 配 。 








HttpClient 不 仅 是 HttpMessageHandler 的 封装 类 ， 配 置 属性 的 宿主 ， 能 够 保存 日 志 消 
息 ， 而 且 还 提供 一 些 辅助 方法 ， 使 发 送 常用 请 求 的 工作 更 加 容易 。 有 了 这 些 辅 助 方法 ， 
HttpClient 可 以 完全 取代 System.Net.NebCLient。 


14.1.5 “辅助 方法 

本 章 的 第 一 个 示例 代码 使 用 了 GetstringAsync 方法 ， 除 此 之 外 还 有 GetStreamAsync 和 
GetByteArrayAsync 方法 。 所 有 这 些 辅助 方法 名 都 以 Async 结尾 ， 说 明 这 些 是 异步 方法 ， 这 
些 方法 的 返回 值 都 是 Task 对 象 。 因 此 ， 我 们 可 以 在 支持 async 和 await 的 平台 上 使 用 这 些 
关键 字 。.NET 4.5 的 原则 是 将 所 有 执行 时 间 超 过 50 毫秒 的 方法 定义 为 异步 方法 ， 这 是 为 
了 鼓励 开发 者 在 设计 应 用 程序 时 ， 不 要 阻塞 用 户 界面 线程 ， 以 创建 响应 性 更 好 的 应 用 。 我 
们 的 示例 使 用 了 返回 任务 的 Result 属性 ， 以 阻塞 调用 线程 ， 返 回 字符 串 结果 。 这 种 方法 
规避 了 NET 4.5 推荐 的 原则 ， 会 带 来 一 些 问题 ， 我 们 将 在 本 章 稍 后 进行 讨论 。 但 是 ， 为 了 
简单 起 见 ， 我 们 将 使 用 Result 来 模拟 同步 请 求 。 
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14.1.6 FHZex 


HttpClient HAIDA A oe RS ET TE, ERA CALA BAER TE. AR ISR 
层 简 化 ， 就 得 到 了 GetAsync 方法 ， 使 用 方法 如 下 : 




















var client = new HttpClient(); 

HttpResponseMessage response; 

response = await client.GetAsync( "http: //www.ietf.org/rfc/rfc2616.txt"); 
HttpContent content = response.Content; 

string rfc2616Text = await content.ReadAsStringAsync(); 


在 这 段 示 例 代码 中 ， 我 们 可 以 访问 响应 对 象 和 内 容 对 象 。 使 用 这 些 对 象 ， 我 们 可 以 检查 
HTTP 标 头 中 的 元 数据 ， 以 决定 如 何 使 用 返回 的 内 容 。 











14.1.7 ”完成 的 请 求 无 异常 

使 用 Httpclient 时 ， 在 默认 情况 下 ， 已 完成 的 HITP 请求 不 会 抛 出 异常 ， 这 与 
HttpWebRequest 的 行为 不 同 。 使 用 HttpCLient 时 ， 如 果 传 输 层 出 现 错误 ，HttpCLient 可 能 
会 抛 出 异常 ， 但 是 3xx、4xx 和 5xx 这 样 的 状态 码 并 不 会 导致 异常 。 而 使 用 HttpWebRequest 
时 ，3xx、4xx 和 5xx 这 样 的 状态 码 也 会 导致 异常 。 我 们 可 以 使 用 HttpResponseMessage 的 
IsSuccessStatusCode 属性 来 判断 状态 码 是 否 为 2xx， 如 果 状 态 码 为 不 成 功 ， 就 可 以 使 用 
EnsureSuccessStatusCode 方法 ， 手 工 触发 一 个 异常 。 








HTTP 请 求 返 回 的 状态 码 经 常 可 以 由 应 用 程序 代码 直接 处 理 ， 不 一 定 需要 抛 出 异常 。 例 如 ， 
对 于 很 多 的 3xx 状态 码 ， 我 们 可 以 向 返回 的 Location 标 头 中 的 URI 发 出 第 二 个 请 求 ， 自 
动 进 行 处 理 ， 对 于 503 Service Unavailable， 我 们 可 以 使 用 重 试 机 制 ， 确 保 暂 时 的 中 断 
不 会 导致 应 用 程序 发 生 严 重 错误 。 本 章 稍 后 部 分 ， 我 们 将 进一步 讨论 如 何 构建 客户 端 ， 对 
HTTP 状态 码 做 出 智能 响应 。 


























14.1.8 ”内 容 为 王 

HttpContent 是 一 个 抽象 类 ，ASP.NET Web API 框 架 对 其 只 提供 少数 具体 实现 。 
HttpContent 对 如 何 处 理发 送 字 节 的 细节 进行 了 抽象 。HttpContent 实例 负责 处 理 如 何 刷 新 
和 定位 流 ， 分 配 和 释放 内 存 ， 以 及 将 CLR 类 型 转换 成 用 于 传输 的 字 节 ， 还 可 以 用 于 访问 
与 HTTP 有 效 载荷 相关 的 标 头 。 


























你 可 以 使 用 第 10 章 介绍 过 的 ReadAs 方法 ， 访 问 一 个 HttpContent 对 象 的 内 容 。 虽 然 
HttpContent 的 抽象 机 制 使 你 无 需 关 心 读 取 网 络 传输 字 节 的 细节 ， 但 是 有 一 个 容易 忽视 
的 关键 细节 ， 需 要 注意 。HttpClient 的 一 些 方法 带 有 一 个 completionOption 参数 。 这 个 
completionOption 参数 决定 了 异步 任务 在 收 到 响应 标 头 后 就 完成 ， 还 是 在 将 完整 的 响应 正 
文 读 入 缓冲 区 后 才 完 成 。 
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你 


可 能 会 希望 在 获得 标 头 之 后 就 将 让 任务 完成 ， 原 因 如 下 : 






































下 的 代码 是 一 个 假设 的 示例 ， 演 示 如 何 使 用 这 一 参数 。 





var httpClient = new HttpClient(); 
httpClient.BaseAddress = new Uri("http://www.ietf.org/rfc/"); 
var tcs = new CancellationTokenSource(); 


var response = await httpClient.GetAsync("rfc2616.txt", 
HttpCompLletionOption.ResponseHeadersRead, tcs.Token); 


// 标 头 已 经 返回 





if (!IsSupported(response.Content.ContentType)) { 
tcs.Cancel(); 
return; 

} 


UIManager userInterfaceManager = new UIManager(); 





// 开始 根据 内 容 类 型 构建 适当 的 UI 


userInterfaceManager .PrepareTheUI(content.ContentType ; 


// FERIA LA BB el BE 


var payload = await response.Content.ReadAsStreamAsync( ) 


// 有 效 载荷 获取 完毕 


userInterfaceManager .Display(payload) ; 


要 实现 这 一 技术 ,UIManager 必须 进行 一 些 线程 同步 控制 ， 
PrepareTheUl 方法 很 可 能 由 不 同 的 线程 调用 ，Display 方法 可 能 需要 等 到 UI 准备 好 才能 

始 执行 。 有 时 ， 为 了 能 够 有 效 地 同时 执行 两 项 任务 ， 以 提高 性 能 ， 这 种 额外 的 设计 工作 是 
值得 的 。 当 然 ， 如 果 你 的 客户 端 必 须 解析 有 效 载荷 才 能 决定 要 显示 什么 内 容 ， 那 么 这 种 技 
术 就 没有 什么 用 处 了 。 








14.1.9 ”取消 请 ; 
我 们 要 讨论 的 GetAsync 方法 的 最 后 一 个 参数 是 CancellationToken。 通 过 创建 一 个 
CancellationToken 并 传 给 GetAsync 方法 ， 发 起 调用 的 对 象 可 以 有 机 会 取消 这 个 Async 操 
作 。 请 注意 ， 取 消 操 作 会 导致 Async 抛 出 异常 ， 你 要 准备 好 捕获 这 个 异常 。 


在 下 面 的 示例 中 ， 如 果 一 个 请 求 不 能 在 一 秒 钟 内 完成 ， 代 码 就 会 取消 这 个 请 求 。 这 段 代码 


只 演示 了 如 何 使 用 Cancel 方法 ， 





[Fact] 


客户 端 可 能 无 法 理解 响应 的 媒体 类 型 ， 如 果 使 用 的 是 计 费 网 络 ， 下 载 正 文 会 浪费 时 间 和 


你 可 能 希望 在 下 载 响应 内 容 的 同时 ， 根 据 响 应 标 头 数据 进行 一 些 处 理 。 


为 Display 方 法 和 





因为 HttpClient 自身 提供 超时 机 制 。 
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public async Task RequestCancelledByCaller() 


{ 
Exception expectedException = null; 
bool done = false; 
var httpClient = new HttpClient(); 
var cts = new CancellationTokenSource(); 
var backgroundRequest = new TaskFactory().StartNew(async () => 
{ 
try 
{ 
var request = new HttpRequestMessage( ) 
{ 
RequestUri = new Uri("http://example.org/largeResource" ) 
J; 
var response = await httpClient.SendAsync(request, 
HttpCompLetionOption.ResponseHeadersRead, cts.Token); 
done = true; 
} 
catch (TaskCanceledException ex) 
{ 
expectedException = ex; 
}, cts.Token); 
// 等 待 请 求 完 成 
Thread.Sleep(1000); 
if (!done) 
cts.Cancel(); 
Assert.NotNull(expectedException); 
} 


14.1.10 SendAsync 


到 目前 为 止 我 们 介绍 的 HttpCLient 的 所 有 方法 都 是 对 单个 方法 SendAsync 的 简单 封装 ， 
SendAsync 的 方法 签名 如 下 : 
public Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, 


HttpCompletionOption completionOption, 
CancellationToken cancellationToken) 


通过 创建 一 个 HttpRequestMessage， 并 设置 其 Method 属性 和 Content 属性 ， 你 可 以 轻易 
使 用 SendAsync 复制 HttpClient 辅助 方法 的 行为 。 但 是 ，HttpRequestMessage 只 能 使 用 一 
次 。 在 发 送 请 求 后 ，HttpRequestMessage 就 会 立即 释放 ， 以 确保 任何 相关 联 的 Content 对 
象 也 得 到 释放 。 在 很 多 情况 下 ， 这 种 做 法 应 该 并 非 必 要 ， 但 是 ， 如 果 一 个 HttpContent 对 
象 封装 了 一 个 只 能 向 前 访问 的 流 ， 那 么 不 重新 初始 化 这 个 流 就 无 法 重新 发 送 这 个 内 容 ， 而 
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HttpContent 对 象 并 没有 提供 这 样 的 接口 。 要 规避 这 个 限制 ， 我 们 可 以 引入 一 个 链接 类 作 
为 请 求 工厂 〈 详 见 第 9 章 )。 


var httpClient = new HttpClient(); 
httpClient.BaseAddress = new Uri("http://www.ietf.org/rfc/"); 


var request = new HttpRequestMessage() { 
RequestUri = new Uri("rfc2616.txt"), 
Method = HttpMethod.Get 

} 


var response = await httpClient.SendAsync(request, 
HttpCompLetionOption.ResponseContentRead, new CancellationToken()); 
SendAsync 方法 是 HttpClient 和 Web API 架 构 的 核心 部 分 。SendAsync 是 HttpMessage 
Handler 使 用 的 主要 方法 ， 而 HttpMessageHandler 是 请 求 和 响应 管道 的 组 件 。 


14.2 客户 端 消息 处 理 程 序 


消息 处 理 程序 (message handler) 是 HttpClient 和 Web API 的 核心 架构 组 件 之 一 。 无 论 是 
在 客户 端 还 是 在 服务 器 上 上， 每 个 请 求 和 响应 消息 都 会 经 过 一 个 类 “ 链 ”， 链 中 的 每 个 类 都 
派生 自 HttpMessageHandLer。 对 于 HttpCLient， 默 认 情 况 下 这 个 链 中 只 有 一 个 处 理 程 序 ; 
HttpClientHandtler。 你 可 以 在 这 个 链 的 开头 插入 更 多 的 HttpMessageHandler 实例 ， 对 默认 
行为 进行 扩展 ， 示 例 14-1 对 此 进行 了 演示 。 


示例 14-1: 向 客户 端 请 求 管 道 添 加 处 理 程序 
var customHandler = new MyCustomHandler() 
{ InnerHandler = new HttpClientHandler()}; 


var client = new HttpClient(customHandler); 


client.GetAsync("http://example.org",content) ; 





示例 14-1 中 的 代码 创建 的 对 象 如 图 14-1 所 示 。 


















SendAsync 











14-1; HttpMessageHandler 的 扩展 性 




















多 个 消息 处 理 程序 可 以 链接 在 一 起 ， 提 供 更 多 的 功能 。 但 是 ， 基 类 HttpMessageHandler 自 
身 没 有 提供 链接 能 力 ， 其 派生 类 DelegatingHandler， 提 供 了 InnerHandler 属性 ， 以 支持 
链接 功能 。 











示例 14-2 展示 了 当 服 务 器 不 支持 PUT 和 DELETE YA, 并且 要 求 请 求 消息 包含 X-HTTP-Method- 
Override 标 头 时 ， 如 何 使 用 消息 处 理 程序 ， 使 客户 端 能 够 对 服务 器 执行 PUT 和 DELETE 操作 。 














T 








示例 14-2: HttpMethodOverrideHandler 
public class HttpMethodOverrideHandler: DelegatingHandler 


{ 
protected override Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, 
System. Threading.CancellationToken cancelLlationToken) 
{ 
if (request.Method == HttpMethod.Put) { 
request.Method = HttpMethod.Post; 
request.Headers.Add('"X-HTTP-Method-Override", "PUT"); 
} 
if (request.Method == HttpMethod.Delete) 
{ 
request.Method = HttpMethod.Post; 
request.Headers.Add("X-HTTP-Method-Override", "DELETE"); 
} 
return base.SendAsync(request, cancellationToken) ; 
} 
} 


DelegatingHandler 的 派生 类 MessageProcessingHandler (参见 示例 14-3)， 进 一 步 简化 了 
处 理 程 序 的 创建 ， 但 只 限于 定制 行为 不 需要 执行 长 时 间 异 步 操 作 的 情况 。 

















示例 14-3: MessageProcessingHandler 
public class HttpMethodOverrideMessageProcessor : MessageProcessingHandler { 
protected override HttpRequestMessage ProcessRequest( 
HttpRequestMessage request, 


CancellationToken cancellationToken) { 


if (request.Method == HttpMethod. Put) 


{ 
request.Method = HttpMethod.Post; 
request.Headers.Add('"X-HTTP-Method-Override", "PUT"); 
} 
if (request.Method == HttpMethod.Delete) 
{ 
request.Method = HttpMethod.Post; 
request.Headers.Add('"X-HTTP-Method-Override", "DELETE"); 
} 


return request; 


} 


protected override HttpResponseMessage ProcessResponse( 
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HttpResponseMessage response, 
CancellationToken cancellationToken) { 
return response; 


} 





使 用 这 些 消息 处 理 程序 进行 功能 扩展 时 ， 你 需要 注意 ， 这 些 处 理 程序 的 执行 线程 经 常会 与 
发 起 请 求 的 线程 不 同 。 如 果 这 个 处 理 程序 尝试 切换 到 请 求 线程 一 一 例如 : 回 到 UI 线程 去 




















更 新 某 个 用 户 界面 的 空间 一 一 那么 可 能 产生 死 锁 。 如 果 最 初 的 请 求 是 阻塞 的 ， 
回 ， 那 么 消息 处 理 程序 切 回 请 求 线程 就 会 导致 死 锁 。 你 可 以 使 用 .NET 4.5 的 
机 制 避免 这 种 问题 ， 但 尽量 不 要 使 用 .Resutt 模拟 同步 请 求 。 


14.2.1 代理 处 理 程 序 
HttpMessageHandler 有 很 多 潜在 的 用 途 ， 其 中 之 一 是 用 做 操控 发 出 请 求 的 代理 























等 待 响应 返 


async await 


E. 下面 的 示 





例 是 Runscope 调试 服务 的 一 个 代理 。 





public class RunscopeMessageHandler : DelegatingHandler 


{ 


private readonly string _bucketKey; 


public RunscopeMessageHandler(string bucketKey, 
HttpMessageHandler innerHandler ) 
{ 


_bucketKey = bucketKey; 
InnerHandler = innerHandler; 


} 


protected override Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, 
CanceLlLationToken cancellationToken) 


var requestUri = request.RequestUri; 
var port = requestUri.Port; 


request.RequestUri = ProxifyUri(requestUri, _bucketKey) ; 
if ((requestUri.Scheme == "http" && port != 80 ) 
|| requestUri.Scheme == "https" && port != 443) 


request.Headers.TryAddWithoutValidation( 
"Runscope-Request-Port", port.ToString()); 


} 


return base.SendAsync(request, cancellationToken) ; 


private Uri ProxifyUri(Uri requestUri, 
string bucketKey, 
string gatewayHost = "runscope.net") 


} 
在 这 个 示例 中 ， 消 息 处 理 程序 将 请 求 URI 修改 为 指向 代理 ， 而 非 原 始 资源 。 
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14.2.2” 伪 响应 处 理 程序 


你 可 以 使 用 消息 处 理 程序 ， 辅 助 客户 端 代码 的 测试 。 如 果 创 建 如 下 的 消息 处 理 程序 : 














public class FakeResponseHandler : DelegatingHandler 


{ 
private readonly Dictionary<Uri, HttpResponseMessage> _FakeResponses 
= new Dictionary<Uri, HttpResponseMessage>(); 
public void AddFakeResponse(Uri uri, HttpResponseMessage responseMessage) 
{ 
_FakeResponses.Add(uri, responseMessage) ; 
} 
protected async override Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, 
CancellationToken cancellationToken) 
{ 
if (_FakeResponses.ContainsKey(request.RequestUr?i) ) 
{ 
return _FakeResponses[request.RequestUri]; 
} 
else 
{ 
return new HttpResponseMessage(HttpStatusCode.NotFound) 
{ RequestMessage = request} 
} 
} 
} 


PRAT LA FA ED BE ee HttpClientHandler ; 


[Fact] 
public async Task CallFakeRequest() 
{ 


var fakeResponseHandler = new FakeResponseHandler(); 
fakeResponseHandler . AddFakeResponse( 

new Uri("http://example.org/test"), 

new HttpResponseMessage(HttpStatusCode.OK)); 


var httpClient = new HttpClient(fakeResponseHandler) ; 


var response1 = await httpClient.GetAsync("http://example.org/notthere"); 
var response2 = await httpClient.GetAsync("http://example.org/test"); 


Assert. Equal(response1.StatusCode ,HttpStatusCode.NotFound) ; 
Assert.Equal(response2.StatusCode, HttpStatusCode.0K); 
} 


为 了 测试 客户 端 服务 ， 你 必须 确保 客户 端 允 许 进 行 HttpCLient 实例 的 注入 。 这 也 是 为 
什么 我 们 推荐 共享 一 个 HttpCLient 实例 ， 而 不 是 对 每 个 请 求 临 时 实例 化 en 
FakeResponseHandler 需要 预先 填充 预期 接收 的 响应 。 使 用 这 种 设置 ， 我 们 可 以 模拟 服务 
链接 ， 进 行 客户 端 代码 测试 : 
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[Fact] 
public async Task ServiceUnderTest() 


{ 


var fakeResponseHandler = new FakeResponseHandler(); 
fakeResponseHandler . AddFakeResponse( 
new Uri("http://example.org/test"), 
new HttpResponseMessage(HttpStatusCode.0K) 
{Content = new StringContent("99")}); 
var httpClient = new HttpClient(fakeResponseHandler ) ; 


var service = new ServiceUnderTest(httpClient) ; 
var value = await service.GetTestVaLue(); 


Assert.Equal(value, 99); 


14.2.3 ”创建 可 以 重用 的 响应 处 理 程序 

在 第 9 章 中 ， 我 们 讨论 了 响应 式 客户 端 (reactive client) 的 概念 ， 这 种 客户 端 解除 了 响应 
处 理 与 请 求 上 下 文 之 间 的 耦合 。 

消息 处 理 程 序 和 HttpClient 管道 是 实现 响应 式 客户 端的 自然 解决 方法 ， 还 可 以 顺便 简化 发 
出 请 求 的 过 程 。 

请 看 示例 14-4 中 的 消息 处 理 程序 。 

示例 14-4: 可 插入 的 响应 处 理 程序 


public abstract class ResponseAction 


{ 








abstract public bool ShouldRespond( 
ClientState state, 
HttpResponseMessage response); 


abstract public HttpResponseMessage HandLeResponse( 
ClientState state, 
HttpResponseMessage response); 


} 


public class ResponseHandler : DelegatingHandler 


{ 


private static readonly List<ResponseAction> _responseActions 
= new List<ResponseAction>(); 


public void AddResponseAction(ResponseAction action) 


{ 
} 


_responseActions.Add(action) ; 


protected override Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, 
CanceLLationToken cancellationToken) 





return base.SendAsync(request, cancellationToken) 
.ContinueWith<HttpResponseMessage>(t => 
AppLyResponseHandler(t.Result)); 


} 


private HttpResponseMessage ApplyResponseHandler( 
HttpResponseMessage response) 


{ 
foreach (var responseAction in _responseActions) 
{ 
if (responseAction.ShouldRespond(response) ) 
{ 
var response = responseAction.HandleResponse(response) ; 
if (response == null) break; 
} 
} 
return response; 
} 


} 


在 这 个 示例 中 ， 我 们 创建 了 一 个 委托 处 理 程 序 ， 如 果 一 个 ResponseAction 的 Should 
Response 返回 ture， 就 将 响应 分 发 到 这 个 ResponseAction 类 。 使 用 这 种 机 制 ， 我 们 可 以 定 
义 和 插 入 任意 多 个 响应 操作 。ShouldResponse 方法 可 以 简单 地 查看 HTTP 状态 码 ， 或 者 实 
现 复杂 的 逻辑 ， 查 看 内 容 类 型 ， 其 至 解析 有 效 载荷 以 寻找 特定 的 标记 。 


发 出 HTTP 请 求 的 过 程 也 得 到 了 简化 ， 如 示例 14-5 所 示 。 








示例 14-5: 使 用 响应 处 理 程序 
var responseHandler = new ResponseHandler() 


{InnerHandler = new HttpClientHandler()}; 


responseHandler .AddAction(new NotFoundHandler()); 
responseHandler .AddAction(new BadRequestHandler()); 
responseHandler .AddAction(new ServiceUnavailableRetryHandler()); 
responseHandler .AddAction(new ContactRenderingHandler()); 


var httpClient = new HttpClient(responseHandler) ; 


httpClient.GetAsync("http://example.org/contacts"); 


14.3 小 结 


HttpClient 是 在 .NET 平台 上 使 用 HTTP 的 一 大 进步 。 通 过 HttpCLient， 我 们 得 到 了 一 个 

和 WebClient 一 样 易 于 使 用 的 接口 ， 而 且 比 HttpWebRequest/HttpWebResponse 功能 更 强 ， 

o 这 个 接口 还 支持 未 来 的 协议 实现 。 使 用 HttpClient， 测 试 变 得 更 加 容易 ， 其 管 
架构 使 我 们 可 以 实现 很 多 横 切 关注 点 ， 还 依然 保持 易 用 性 。 
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从 广义 上 说 ， 计 算 机 系统 安全 包括 了 很 多 主题 和 技术 ， 从 加 密 算法 一 直到 系统 可 用 性 和 灾 
难 恢 复 系统 ， 都 属于 计算 机 安全 的 范畴 。 本 章 并 不 会 讨论 这 么 多 的 内 容 。 我 们 将 关注 与 
Web API 密切 相关 的 安全 问题 一 一 有 具体 而 言 ， 就 是 传输 安全 、 身 份 验证 和 授权 。 因 此 ， 在 
接 下 来 的 小 节 中 ， 我 们 将 从 理论 和 实践 的 角度 ， 以 ASP.NET Web API 为 支持 技术 ， 解 决 
这 些 安全 问题 。 

















下 一 章 是 对 本 章 内 容 的 补充 ， 将 只 关注 OAuth 2.0 框架 ， 解 决 基于 HTTP 的 API 中 访问 控 
制 的 一 组 协议 和 模式 。 


15.1 传输 安全 


传输 信息 的 保密 性 和 完整 性 是 重要 的 安全 需求 ， 在 设计 和 实现 分 布 式 系统 时 必须 满足 这 些 
需求 。 糟 糕 的 是 ，HTTP 协议 几乎 不 提供 安全 方面 的 支持 。 因 此 ， 开 发 者 们 通常 采取 的 解 
决 办 法 是 ， 在 一 个 安全 传输 层 上 使 用 HTTP 协议 ， 如 RFC 1818 定义 的 “HTTP Over TLS”, 
形成 了 我 们 所 知 的 HTTPS。 简 单 地 说 ，RFC 1818 规范 声明 ， 如 果 客 户 端 使 用 https 方案 ， 
对 一 个 URI 执行 HTTP 请 求 〈 例 如 : https:/www.example.net)， 那 么 这 个 HTTP 协议 就 位 
于 一 个 安全 传输 层 (TLS 或 SSL) 之 上 ,而 不 是 直接 在 TCP 层 上 ， 如 图 15-1 所 示 。 使 用 
这 种 方式 ， 请 求 和 响应 消息 在 两 个 传输 端点 之 间 进 行 传送 时 ， 都 受到 传输 协议 的 保护 。 





























RFC 5246 定义 的 TLS (Transport Layer Security protocol， 传 输 层 安全 协议 )， 是 SSL (Secure 
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Socket Layer protocol， 安 全 套 接 层 协议 ) 的 改进 版 。 这 两 个 协议 都 是 为 了 在 两 个 通信 实 
体 一 一 通常 称 为 对 等 方 (peer) 之 间 ， 提 供 一 个 安全 的 双向 连接 ， 这 个 连接 具有 如 下 
特征 。 








。 ZÆ (integrity) 
FENIE AWE RE E S A Ts ERA AE. MRE EE] 
第 三 方 的 修改 ， 或 者 转发 ， 系 统 都 能 检测 发 现 ， 并 终止 连接 。 




















。 保密 性 (confidentiality) 
每 个 对 等 方 都 得 到 保证 ， 只 有 远 端的 对 等 方 能 查看 发 送 的 字 市 流 。 





http://www.example.net https://www.example.net 


HTTP HTTP 应 用 层 


TCP TLS/SSL 传输 层 


TCP 























图 15-1; Https 方案 和 传输 安全 


除了 完整 性 和 保密 性 ，TLS 协议 还 能 够 执行 对 等 身份 验证 ， 为 客户 端 或 服务 器 提供 远 端 对 
等 方 的 验证 身份 。 非 常 重要 的 一 点 是 ， 在 用 于 HTTP 时 ，TLS 还 负责 执行 服务 器 身份 验证 
的 基本 任务 ， 在 客户 端 发 送 任何 请 求 消息 之 前 ， 为 客户 端 提供 服务 器 的 验证 身份 。 我 们 将 
在 15.3 节 详 细 讨 论 基于 TLS 的 身份 验证 。 








TLS 协议 自身 分 为 两 个 主要 的 子 协 议 。 记 录 子 协议 (record subprotocol) 使 用 对 称 加 密 方 
案 和 MAC (Message Authentication Codes， 消 息 认证 码 )， 保护 字 节 流 的 交换 ， 提 供 完整 
性 和 保密 性 。 记 录 子 协议 位 于 一 个 可 靠 传 输 层 (如 TCP) 之 上 ， 由 三 层 组 成 。 第 一 层 将 进 
入 的 字 节 流 划 分 为 记录 ， 每 个 记录 最 长 为 16 KB。 第 二 层 对 每 个 记录 进行 压缩 。 最 后 一 层 
使 用 MAC-then-Encrypt 的 方式 进行 加 密 保护 ， 即 : 首先 对 已 加 密 的 记录 加 上 一 个 序列 号 ， 
计算 出 一 个 MAC 值 ， 然 后 对 已 加 密 记录 和 MAC 值 一 起 进行 加 密 。 











握手 子 协议 (handshake subprotocol) 用 于 建立 TLS 操作 参数 ， 即 记录 子 协 议 使 用 的 安全 
参数 (例如: 加 密 算法 和 MAC 密 钥 )。 握 竹子 协议 支持 多 种 密 钥 生成 技术 。 但 是 ， 在 用 于 
Web 时 ， 最 常见 的 做 法 是 使 用 基于 公用 密 钥 的 加 密 方法 和 证 书 。 附 录 G 对 这 一 内 容 进行 了 
简要 的 介绍 ， 并 展示 了 如 何 创建 在 开发 环境 中 使 用 的 密 钥 和 证 书 。 











注 1: 在 本 章 余 下 部 分 ， 我 们 将 二 者 都 称 为 TLS。 
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15.2 在 ASP.NET Web API 中 使 用 TLS 


TLS 协议 运行 于 传输 层 之 上 ， 这 意味 着 TLS 协议 是 由 低层 的 HTTP 托管 基础 结构 实现 的 ， 
在 Windows 上 就 是 内 核 模式 的 HTTP.SYS 驱动 程序 。 因 此 ，TLS 相关 的 大 多 数 配 置 是 
在 ASP.NET Web API 之 外 完成 的 ， 而且 US 托管 方式 和 自 托 管 方式 下 的 TLS 配置 也 有 所 
不 同 。 


15.2.1 1IS 托 管 时 使 用 TLS 
在 IIS E, TLS 是 通过 给 站 点 添加 HTTPS 绑 定 进行 配置 的 ， 如 图 15-2 所 示 。 





Site Bindings ™ Q| X 
Type Host Name Port IP Address | Binding Infor... 


http www.example.net 80 x 
Add Site Binding EH = a} 


Type: IP address: 


Host name: 














SSL certificate: 


www.example.net 























图 15-2: 给 一 个 站 点 添加 HTTPS 绑 定 


添加 HTTPS 绑 定 由 服务 器 证 书 进行 配置 ， 这 个 证 书 必 须 安 装 在 本 地 计算 机 的 个 人 存储 ， 
有 一 个 相关 的 私有 密 钥 ， 并 有 一 个 有 效 证 书 路 径 ， 指 向 一 个 信任 的 根 证 书 颁 发 机 构 。 除 此 
之 外 ， 你 不 需要 对 TIS 配置 或 Web API 配置 进行 任何 修改 。 





图 15-3 展示 了 浏览 器 通过 HTTPS 执行 请 求 的 用 户 界面 。 请 注意 ， 界 面 上 的 信息 既 有 服务 
器 的 标识 (www.example.net) ， 也 有 证 书 颁 发 机 构 的 名 称 (“Demo Certification Authority”)。 





314 | 第 15 章 





口 https://www.example 


@ https://www.example.net/api/hello 


Hello Secul 日 www.example.net 





he identity of this website has been verified by 
Demo Certification Authority. 


ertificate information 


日 Your connection to www.example.net is encrypted 
with 128-bit encryption. 


The connection uses TLS 1.0. 


The connection is encrypted using AES_128 CBC, 
with SHA1 for message authentication and RSA as 
the key exchange mechanism. 
The connection is not compressed. 

w Site information 
You have never visited this site before today. 


What do these mean? 














图 15-3; {FA HTTPS 访问 ASP.NET Web API 


在 IIS 7.5 中 ， 多 个 站 点 的 HTTP 绑 定 可 以 配置 为 指向 同一 个 IP 地 址 和 端口 ， 因 为 请 求解 
复 用 (demultiplexing， 对 选中 的 站 点 进行 请 求 分 发 ) 会 使 用 请 求 的 Host 标 头 中 的 主机 名 。 
但 是 ， 使 用 不 同 证 书 的 多 个 HTTPS 绑 定 不 能 配置 为 执行 同一 个 卫 地 址 和 端口 〈 因 为 早 在 
收 到 HTTP 请 求 之 前 ， 建 立 TLS 连接 时 就 需要 使 用 证 书 )。 因 此 ， 要 在 一 个 服务 器 上 托管 
多 个 HTTPS 站 点 ， 我 们 可 以 采取 如 下 方法 。 











。 为 每 个 HTTPS 绑 定 使 用 不 同 的 IP 地 址 或 端口 。 
。 对 所 有 绑 定 使 用 同一 个 证 书 ， 这 通常 意味 着 在 这 个 证 书 的 主体 名 中 使 用 通配符 。 你 也 可 
以 选择 使 用 主体 别名 (Subject Alternative Name) 扩展 ， 为 同一 个 证 书 定义 多 个 主体 名 。 














主体 别名 


X.509 证 书 规范 定义 了 一 个 扩展 字段 主体 别名 (Subject Alternative Name) ， 允 许 在 一 个 
证 书 中 包含 一 个 或 多 个 主体 名 。 例 如 ， 在 这 本 书 编写 之 时 ， 到 https://www.google.com 
的 连接 使 用 一 个 包含 44 个 别名 的 X.509 服务 器 证 书 ， 其 中 有 : *.google.com、*.android. 


com, *.google.com.ar, *.google.ca, VA% *.google.pt。 











RFC 4366 定义 了 一 个 新 的 TLS 扩展 ， 名 为 SNI (Server Name Indication， 服 务 器 名 称 标 
识 )， 这 一 扩展 将 HTTP 主机 名 添加 到 TLS 的 初始 握手 通信 中 。 使 用 这 一 额外 的 信息 ， 即 
便 建立 的 TOP 连接 指向 同一 个 全 地址 和 端口 ， 服 务 器 也 可 以 为 每 个 主机 名 使 用 不 同 的 
证 书 。 遗憾 的 是 ， 只 有 IIS 8.0 或 更 高 版 本 才 支 持 SNL, US 7.5 或 较 低 版 本 都 不 提供 这 一 
功能 。 

















15.2.2 自 托 管 时 使 用 TLS 


当 使 用 自 托管 时 ， 你 可 以 使 用 命令 行 工具 netsh， 进 行 TSL 配置 : 





netsh http add sslcert ipport=0.0.0.0:port certhash=thumbprint appid={app-guid} 





其 中 : 


e ipport 是 服务 监听 的 IP 地 址 和 端口 〈 特 殊 地 址 0.0.0.0 匹配 本 机 的 任何 卫 地 址 ) ; 
e certhash 是 服务 器 证 书 的 SHA-1 散 列 值 的 十 六 进 制 表示 ; 
。 appid 只 是 用 于 标识 应 用 程序 的 一 个 GUID。 


自 托管 时 所 选 的 服务 器 证 书 与 IIS 托管 时 的 要 求 相 同 ， 即 : 证 书 必须 安装 在 本 地 计算 机 的 
个 人 存储 ， 有 一 个 相关 的 私有 密 钥 ， 并 有 一 个 有 效 证 书 路 径 ， 指 向 一 个 信任 的 根 证 书 颁 发 
机 构 。 唯 一 的 区 别 是 ，ASP.NET Web API 配置 需要 在 自 托管 监听 地 址 中 使 用 https 格式 : 
































var config = new HttpSelfHostConfiguration("https: //www.example.net:8443"); 


传输 安全 就 介绍 到 这 里 了 。 下 一 市 将 介绍 身份 验证 。 


15.3 身份 验证 


根据 RFC 4949 (因特网 安全 词典 ) 的 定义 ， 身 份 验 证 (authentication) 是 “验证 一 个 系统 
实体 或 系统 资源 具有 某 种 属性 值 的 过 程 ”。 对 HTTP 而 言 ， 客 户 端 和 服务 器 是 两 个 显 而 易 
见 的 系统 实体 ， 这 两 个 实体 通常 都 需要 进行 属性 验证 。 


一 方面 ， 我 们 需要 进行 服务 器 身份 验证 ， 以 预先 向 客户 端 保证 ， 请 求 消息 只 会 发 送 给 正确 
的 源 服务 器 一 一 即 : 指定 资源 所 在 的 服务 器 或 应 该 创建 指定 资源 的 服务 器 。 在 这 种 情况 
下 ， 消 息 的 发 送 者 需要 在 发 送 消 息 之 前 ， 对 消息 的 接收 者 进行 身份 验证 ， 通 常 是 认证 传输 
连接 的 另 一 端 。 服 务 器 身份 验证 也 需要 检验 收 到 的 响应 消息 ， 是 否 确实 由 正确 的 服务 器 产 
生 。 与 客户 端 交 互 的 资源 由 URI 标识， 因此 身份 验证 过 程 要 检验 的 主要 属性 就 是 URI 中 
主机 名 (IP 地 址 或 DNS 名) 的 所 有 权 。 


男 一 方面 ， 客 户 端 身份 验证 为 服务 器 提供 身份 信息 ， 用 于 判断 请 求 消息 是 否 应 该 得 到 授 
权 一 一 即 : 所 请 求 的 方法 是 否 适用 于 指定 的 资源 。 在 这 种 情况 下 ， 身 份 验证 过 程 要 检验 的 
属性 与 上 下 文 有 关 ， 可 能 是 简单 的 不 透明 标识 符 ， 如 用 户 名 ， 也 可 能 是 一 个 属性 集合 ， 例 
如 : 电子 邮件 、 姓 名 、 和 角色 、 地 址 ， 以 及 银行 账号 和 社会 安全 号 码 。 











我 们 在 随后 的 儿 市 中 将 会 看 到 ， 这 些 身份 验证 需求 可 以 在 两 个 层次 上 实现 : 








。 通过 在 安全 连接 上 发 送 和 接收 HTTP 消息 ， 在 传输 层 实现 身份 验证 ，; 
。 通过 在 消息 上 附加 用 于 对 身份 验证 消息 源 的 安全 信息 ， 在 消息 层 实 现 身 份 验证 。 
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但 是 ， 在 介绍 这 些 身份 验证 机 制 的 细节 之 前 ， 我 们 要 首先 了 解 NET 框架 如 何 表 示 身 
份 一 一 即 身份 验证 过 程 的 输出 。 





15.3.1 声明 模型 


NET 框架 从 版 本 1.0 开始 ， 提 供 两 个 表示 身份 的 接口 : IPrincipal 和 IIdentity (参见 
图 15-4)。IPrincipal 接口 “表示 运行 代码 的 用 户 的 安全 上 下 文 "。 例 如 ， 在 HTTP 请 求 
处 理 上 下 文中 ，IPrincipal 接口 表示 请 求 消息 的 产生 者 一 一 HTTP 客户 端 。IPrincipal 接 
口 提供 一 个 IsInRote 方法 ， 用 于 查询 请 求 者 是 否 属 于 指定 的 角色 ， 还 提供 一 个 类 型 为 
IIdentity 的 Identity 属性 。IIdentity 接口 通过 三 个 属性 表示 一 个 用 户 标识 : 























e AuthenticationType 字符 串 ; 
。 Nane FA 
e IsAuthenticated FIFE., 














>| 








| Principal 众 | Identity 
Interface Interface 
oo a 
© Methods “| E Properties 
@ sinRole * AuthenticationType 
* lsAuthenticated 
# Name 




















15-4; IPrincipal 和 IIdentity 接口 


我 们 可 以 通过 Thread.CurrentPricipal 静态 属性 ， 访 问 当 前 用 户 对 象 ( 即 运行 当前 
代码 的 用 户 的 安全 上 下 文 对 象 )， 也 可 以 通过 上 下 文 相关 的 属性 (例如: ASP.NET 
MVC 的 System.Web.Mvc.Controller.User 属 性 ， 或 WCF AY System.ServiceModel. 
ServiceSecurityContext.PrimaryIdentity) 获得 这 一 信息 。 在 ASP.NET Web API EFX 
中 ，ApiController.User 属性 的 类 型 也 是 IPrincipal， 可 以 用 于 访问 当前 主体 。 

















NET 框架 也 提供 IPrincipal 和 IIdentity 接口 的 一 组 具体 实现 : 








e GenericPrincipal, WindowsPrincipal 和 RolePrincipal 类 实现 了 IPrincipal 接口 ; 
e GenericIdentity, WindowsIdentity 和 FormsIdentity 类 实现 了 IIdentity 接口 。 


然而 ， 旧 有 模型 的 用 户 标 识 概念 颇 为 狭 附 ， 将 其 限制 为 一 个 简单 的 字符 串 和 一 个 角色 查询 


方法 。 而 且 ， 这 种 模型 假设 存在 一 个 隐 含 的 标识 机 构 ， 而 实际 上 身份 验证 信息 可 以 来 自 多 
个 提供 方 ， 既 可 以 是 社会 站 点 ， 也 可 以 是 组 织 目录 。 




















声明 模型 的 设计 目标 是 ， 基 于 声明 (claim) 概念 ， 定 义 表示 用 户 标 识 的 一 种 新 方式 ， 以 克 





服 旧 模 型 的 限制 。4 Guide to Claims-Based Identity and Access Control (Microsoft Patterns & 


Practices) 一 书 将 claim 定义 为 “一 个 主体 对 于 


自己 或 其 他 主体 所 做 的 声明 ， 





例如 : 一 个 名 





字 、 身 份 、 密 钥 、 群 组 、 权 限 或 能 力 ”。 我 们 要 强调 这 一 定义 的 两 个 特征 。 首 先 ， 这 个 定 
义 非常 宽泛 ， 包 括 了 不 同 的 身份 属性 ， 从 简单 的 名 字 标 识 符 到 身份 验证 能 力 。 其 次 ， 这 个 
定义 明确 指出 ， 声 明 可 以 由 多 方 做 出 ， 被 标识 的 主体 也 可 以 做 出 声明 ( 自 声明 )。 


NET 框架 4.5 使 用 这 种 声明 模型 表示 用 于 标识 ， 还 引入 了 System.Security.Claims 命名 空 





间 ， 甚 中 包含 与 声明 模型 相关 的 几 个 类 。CLaims 类 (参见 








。 Issuer 是 一 个 字符 串 ， 标 识 做 出 标识 声明 的 机 构 ， 


。 Type 是 一 个 字符 串 ， 描 述 声 明 类 型 
。 Value 也 是 一 个 字符 串 ， 包 含 声 明 值 。 





图 15-5) 由 三 个 核心 属性 组 成 : 








Claim A | 


中 ldentity 





Claimsldentity 
Class Class 
c=) y | # Claims: lEnumerable<Claim> a 
& Properties 下 < 日 Properties 





* Issuer: string 
Originallssuer : string 
Properties : IDictionary<string, string> 


# Subject 





Value : string 








# 
# 
# Type:string 
# 
# 


ValueType : string 








Label : string 
Name: string 


mm 





* Actor: Claimsldentity 
AuthenticationType : string 
BootstrapContext : object 
IsAuthenticated : bool 


NameClaimType : string 
RoleClaimType : string 














15-5; Claim 和 ClaimsIdentity 类 





下 面 的 代码 段 演示 了 从 进程 的 Windows 标识 得 到 的 声明 的 三 个 Claim 核心 属 











[Fact] 


public void Claims_have_an_issuer_a_type_and_a_value() 


{ 


AppDomain. CurrentDomain.SetPrincipalPolicy( 
PrincipalPolicy.WindowsPrincipal) ; 
var identity = Thread.CurrentPrincipal.Identity as ClaimsIdentity; 


Assert.NotNull(identity) ; 
var nameClaim = identity.Claims 


.First(c => c.Type == ClaimsIdentity.DefaultNameClaimType) ; 
Assert.Equal(identity, nameClaim. Subject); 


Assert.Equal("AD AUTHORITY", nameClaim. Issuer); 
Assert.Equal(ClaimTypes.Name, nameClaim. Type); 


Assert.Equal( 


"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", 


nameClaim.Type); 


Assert.True(nameClaim.Value.EndsWith("pedro")); 





性 : 
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ClaimType 类 包含 一 组 常用 的 声明 类 型 标识 符 : 


public static class ClaimTypes 


{ 
public 
public 
public 
public 
public 
public 
public 
public 
public 


} 


const 
const 
const 
const 
const 
const 
const 
const 
const 





string Role = "http://schemas.microsoft.com/.. 


string AuthenticationInstant =... 
string AuthenticationMethod =... 
string AuthorizationDecision = ... 
string Dns = ... 

string Email =... 

string MobilePhone = ... 

string Name =... 

string NameIdentifier =... 


// 省 略 其 他 成 员 


NET 框架 4.5 还 引入 了 两 个 新 的 基于 声明 的 具体 类 : 





e ClaimsIdentity 类 将 用 户 标 识 表示 为 一 个 声明 序列 ， 


e ClaimsPrincipal 类 将 用 户 身份 表示 为 一 个 或 多 个 基于 声明 的 标识 。 


./claims/role"; 


请 注意 ， 这 些 新 类 也 实现 了 原 有 的 Principal 和 Identity 接口 ， 因 此 可 以 用 于 遗 
留 代 码 。 此 外 ， 原 有 的 表示 用 户 身 份 和 标识 的 具体 类 ， 例 如 : WindowsPrincipal 或 



























































FormsIdentity， 也 经 过 重新 改造 ， 继 承 这 些 新 的 基于 声明 的 类 ， 如 图 15-6 所 示 。 
9 IPrincipal 中 lldentity 
| ClaimsPrincipal A Claimsldentity A 
Class Class 
O 了 oa Y 
& Properties & Identities S Properties 
# Claims EE >> * Actor 
* ClaimsPrincipalSelector * AuthenticationType 
* Current * BootstrapContext 
* Identity * Claims 
* PrimaryldentitySelector * lsAuthenticated 
* Label 
# Name 
£ NameClaimType 
£ RoleClaimType 
_ i 一 —= 
| GenericPrincipal ¥ Genericldentity = 
Class Class 
+ ClaimsPrincipal + Claimsidentity 
2 Us 
| RolePrincipal y Formsldentity y 
|__| Class FO Class 
+ ClaimsPrincipal + Claimsidentity 
ge] 器 
( WindowsPrincipal ¥ Windowsidentity ¥ to 
class Class 
+ ClaimsPrincipal + Claimsidentity 
ao oO 























Æ 15-6; ClaimsPrincipal 类 和 ClaimsIdentity 类 
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在 本 章 余下 的 部 分 ， 我 们 将 用 这 些 新 的 基于 声明 的 类 表示 用 户 标 识 。 








Windows 身份 验证 基础 和 .NET 框架 


具有 声明 意识 的 应 用 程序 的 类 模型 最 早出 现在 2009 年 ， 是 .NET 平台 的 一 个 扩展 ， 称 
A Windows 身份 验证 基础 (Windows Identity Foundation)。 这 个 类 模型 大 部 分 位 于 
Microsoft.IdentityModel 命名 空间 中 。 从 NET 框架 4.5 开始 ， 这 个 类 模型 成 为 .NET 
框架 的 重要 组 成 部 分 ， 并 移植 到 到 System 命名 空间 中 ,使 用 原 有 类 模型 的 代码 将 无 法 


运行 。 











在 分 布 式 系 统 中 ， 身 份 凭证 的 提供 者 ， 可 能 并 不 是 对 这 些 感 兴趣 的 一 方 。 在 这 些 情况 下 ， 
我 们 需要 对 二 者 加 以 区 分 : 


。 RERS (identity provider) 是 一 个 实体 ， 发 布 关 于 主体 的 凭证 声明 ， 这 个 声明 通常 
包含 该 实体 有 权 发 布 或 验证 过 的 信息 ， 

。 Riky (relying party) 是 使 用 凭证 提供 方 发 布 的 凭证 声明 的 实体 ( 即 : 使 用 方 或 
依赖 方 ) 。 


图 15-7 展示 了 凭证 提供 方 和 信赖 方 之 间 的 关系 。 分 布 式 身份 验证 协议 (如 WS-Federation) 
的 任务 如 下 : 





。 为 凭证 信赖 方 提 供 请 求 机 制 ， 向 凭证 提供 方 请 求 获得 关于 一 个 主体 的 号 份 声明 ， 
。 为 凭证 提供 方 提供 发 出 声明 的 机 制 ， 并 使 发 出 请 求 的 信赖 方 能 够 获得 这 些 声 明 。 








使 用 

















15-7; 凭证 提供 方 和 凭证 信赖 方 
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15.3.2 ”获取 和 设置 当前 用 户 对 象 


.NET 框架 早期 的 版 本 通过 静态 属性 Thread. he 并 行当 前 用 户 对 象 的 获取 
和 设置 。 但 是 ， 这 一 技术 现在 存在 两 个 问题 。 ,一 个 请 求 不 一 定 是 由 单个 线程 执行 

的 。 特 别 是 异步 编程 模型 的 广泛 使 用 ， a 条 线 程 关联 在 一 起 。 
第 二 ,一 些 NET 框架 组 件 ， 例 如 ASP.NET 和 WCF， 定 义 了 访问 和 定义 当前 用 户 身份 信 
息 的 其 他 途径 。 例 如 ， 在 ASP.NET 中 ，HttpContext 类 有 一 个 静态 属性 User， 其 类 型 为 
Principal, 用 户 身份 信息 在 多 处 保存 ， 增加 了 信息 不 一 致 的 可 能 性 。 


在 ASP.NET Web API 1.0 中 ， 托 管 方式 决定 了 应 该 如 何在 消息 处 理 程序 管道 中 设置 当前 用 
户 对 象 。 如 果 你 使 用 的 是 自 托管 ， 给 Thread.CurrentPrincipal 赋值 即 可 。 但 是 ， 如 果 使 用 
的 是 Web 托管 ， 你 必须 给 Thread.CurrentPrincipal 和 HttpContext.Current.User 都 赋值 。 
一 个 常用 的 技巧 是 检查 HttpContext.Current 不 为 null; 



































Thread.CurrentPrincipal = principalToAssign; 
if (HttpContext.Current != null) 


HttpContext.Current.User = principalToAssign; 


} 


可 是 ， 如 果 使 用 这 种 技术 ， 即 便 是 采用 自 托管 方式 ， 也 会 造成 应 用 程序 对 System.Web 程序 
集 的 依赖 。 


在 ASP.NET Web API 2.0 中 ， 你 可 以 使 用 新 的 HttpRequestContext 类 ， 解 决 这 一 问题 。 首 
先 ， 你 必须 获得 当前 用 户 对 象 ， 将 其 赋 给 当前 的 请 求 对 象 ， 而 不 是 设置 静态 属性 。 其 次 ， 
不 同 的 托管 方式 可 以 使 用 不 同 的 HttpRequestContext 实现 : 




















。 自 托管 使 用 SeLfHostHttpRequestContext， 直 接 给 Thread.CurrentPrincipal 属性 赋值 ; 

。 Web 托管 使 用 WebHostHttpRequestContext, 24 Thread.CurrentPrincipal 和 HttpContext. 
Current.User 届 性 都 赋值 ， 

© OWIN 托管 使 用 OwinHttpRequestContext, 24 Thread.CurrentPrincipal 和 当前 的 OWIN 
上 下 文 对 象 赋值 。 


遗憾 的 是 ，Web API 的 这 两 个 版 本 没有 通用 的 方法 。 在 这 本 书 的 后 面部 分 ， 我 们 将 主要 使 
用 Web API 2.0 版 本 的 方法 。 


15.3.3 ”基于 传输 的 身份 验证 

我 们 前 面 介绍 过 ，TLS 协议 也 可 以 用 于 身份 认证 ， 为 传输 方 提供 远 端 对 等 方 的 身份 标识 
在 接 下 来 的 小 节 中 ， 我 们 将 介绍 如 何 使 用 TLS 的 这 个 功能 ， 获 取 服 务 器 和 客户 端 身份 
验证 。 



































15.3.4 服务 器 身份 验证 

当 客 户 端 使 用 https 请 求 URI 发 送 HTTP 请 求 时 ， 所 用 的 连接 必须 始终 受到 TLS 或 SSL 
的 保护 ， 以 确保 发 送 销 息 的 完整 性 和 保密 性 。 除 此 之 外 ， 客 户 端 还 必须 在 担 手 协商 中 获得 
服务 器 证 书 ， 将 其 中 的 标识 与 URI 主机 名 进行 比较 ， 以 检查 服务 器 身份 。 这 种 验证 能 确保 
HTTP 请 求 消息 只 发 送 给 通过 身份 验证 的 服务 器 ， 解 决 了 服务 器 身份 验证 问题 。 


从 证 书 中 获得 服务 器 标识 的 方法 如 下 : 





。 如 果 证 书包 含 一 个 类 型 为 DNS 名 的 主体 别名 (subject alternative name) 扩展 ， 那 么 就 
使 用 这 个 值 ; 
。 否则 ， 就 使 用 证 书 的 主体 字段 中 的 常用 名 (common name), 








如 果 主 体 别名 扩展 包含 多 个 名 字 ， 那 么 URI 主机 名 可 以 匹配 其 中 任何 一 个 。 有 了 这 个 功 
能 ， 我 们 可 以 对 不 同 主机 名 (例如 : www.example.net 和 api.example.net) 使 用 同一 个 证 
书 ， 当 这 些 主 机 名 都 绑 定 到 同一 个 IP 地 址 时 会 十 分 有 用 。 例 如 : Æ NIS 7.5 之 前 的 版 本 中 ， 
使 用 同一 个 全 地址 和 端口 的 不 同 https 绑 定 都 必须 使 用 同一 个 证 书 。 





服务 器 证 书 中 的 名 字 也 可 以 包含 通配符 (例如: *.example.net)。 举 个 例子 ，*.example PE 
配 主机 名 www.example.net。 如 果 服 务 器 有 多 个 租户 ， 在 服务 器 证 书 颁 发 时 还 无 法 知道 主 
机 名 ， 就 可 以 在 名 字 中 使 用 通配符 。 例 如 : Azure Service Bus 目前 使 用 的 证 书包 含 两 个 别 
名 : *.servicebus.windows.net 和 servicebus.windows.net， 可 以 匹配 如 mytenant-name. 


servicebus.windows.com 这 样 的 主机 名 。 








目前 ， 基 于 TLS 的 服务 器 身份 验证 使 用 PKI 信任 模式 ( 详 见 附录 G)， 在 这 种 模式 中 ， 
整体 安全 依赖 于 一 组 认证 机 构 的 正确 行为 。 遗 憾 的 是 ，PKI 信任 模式 很 容易 受到 MITM 
(Man-In-The-Middle， 中 间 人 ) 攻击 。 例 如 ， 如 果 攻 击 者 控制 了 CA (Certificate Authority， 
认证 授权 机 构 ) 的 名 字 验 证 程序 ， 就 可 以 将 攻击 者 控制 的 公用 密 钥 与 他 人 的 名 字 进 行 绑 
定 ， 伪 造 证 书 。 如 果 攻 击 者 能 够 使 用 CA 的 密 钥 颁发 伪造 的 证 书 ， 也 会 导致 同样 的 后 果 。 





一 些 平台 在 默认 情况 下 配置 了 很 多 受信 任 的 根 证 书 颁发 机 构 (root certification authority) , 
使 这 一 问题 更 加 严重 。 例 如 ，Mozilla 项 目 〈 即 : Fixfox 浏览 器 ) 使 用 的 根 证 书 列表 有 150 多 个 
不 同 的 条 目 (参见 https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/)。 
请 注意 ， 如 果 攻 击 者 控制 了 这 些 证 书 颁发 机 构 中 的 任何 一 个 ， 那 么 就 可 以 对 任何 服务 器 发 
起 MITM 攻击 ， 即 便 该 服务 器 的 证 书 不 是 由 受 控制 的 机 构 颁发 的 ， 也 不 能 幸免 。 














要 解决 这 个 安全 问题 ， 一 个 方法 是 在 服务 器 证 书 验 证 过 程 中 加 入 额外 的 上 下 文 要 求 。 其 中 
一 个 额外 要 求 称 为 证 书 识 别 (certificate pinning) ， 将 链 中 的 证 书 与 一 组 固定 的 已 知 证 书 进 
行 比较 ， 这 组 已 知 证 书 称 为 锁定 证 书 集合 (pinset) 。 如 果 客 户 端 与 服务 器 的 第 一 个 交互 确 
定 没 有 受到 MITM 攻击 ， 服 务 器 提供 的 证 书 链 就 可 以 用 于 构建 锁定 证 书 集合 。 选 择 这 种 方 
式 ， 是 因为 服务 器 改变 其 使 用 的 根 证 书 的 概率 很 低 。 
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另 一 个 方法 是 使 用 一 个 静态 的 基于 上 下 文 的 锁定 证 书 集合 。 例 如 ，Chromium 浏览 器 ( 参 
JL http://blog.chromium.org/201 1/06/new-chromium-security-features-june.html) 对 用 户 连 接 
到 Gmail 和 谷歌 账号 服务 器 时 使 用 的 CA 进行 了 限制 。Twitter API 安全 最 佳 实践 (参见 
https://dev.twitter.com/overview/api/ssl) 是 使 用 这 种 方法 的 另 一 个 例子 ， 其 中 声称 任何 客户 
端 应 用 程序 都 应 该 确保 Twitter 服务 器 返回 的 证 书 链 包含 一 部 分 已 核准 的 CA。 











a 


在 使 用 HttpClient 时 ， 你 可 以 使 用 WebRequestHandler 客户 端 处 理 程 序 和 一 个 定制 的 证 
验证 回调 程序 ， 强 制 进行 证 书 识别 ， 代 码 如 下 所 示 : 














private readonly CertThumbprintSet verisignCerts = new CertThumbprintSet( 
"85371ca6e550143dce2803471bde3a09e8f8770f", 
"62f3c89771da4ce01a91fc13e02b6057b4547a1d", 


"4eb6d578499b1ccf5f581ead56be3d9b6744a5e5", 
"5deb8f339e264c19f6686f5f8f32b54a4c46b476" 


); 
[Fact] 
public async Task Twitter_cert_pinning() 
{ 
var wrh = new WebRequestHandler(); 
wrh.ServerCertificateValidationCallback = 
(sender, certificate, chain, errors) => 
{ 
var caCerts = chain.ChainElements 
.Cast<X509ChainElLement>().Skip(1) 
.Select(elem => elem.Certificate); 
return errors == SslPolicyErrors.None && 
caCerts.Any(cert => 
verisignCerts.Contains(cert.GetCertHashString())); 
}; 
using (var client = new HttpClient(wrh)) 
{ 
await client.GetAsync("https://api.twitter.com"); 
var exc = Assert. Throws<AggregateException>(() => 
client.GetAsync("https://api.github.com/").Result); 
Assert. IsType<HttpRequestException>(exc.InnerExceptions[0]); 
} 
} 


verisignCerts 中 包含 了 pinset， 是 一 组 保存 在 定制 的 CertThumbprintset 类 中 的 证 书 指纹 ， 
CertThumbprintSet 定义 如 下 : 





public class CertThumbprintSet : HashSet<string> 


{ 
public CertThumbprintSet(params string[] thumbs) 


:base(thumbs, StringComparer .OrdinalIgnoreCase) 


{} 
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示例 中 使 用 的 HttpClient 以 一 个 显示 实例 化 的 WebRequestHandler 为 参数 进行 创建 。 这 个 
处 理 程序 提供 了 ServerCertificateValidationCallback 属性 ， 可 以 定义 为 一 个 委托 方法 ， 
由 运行 时 在 标准 的 内 建 证 书 验 证 过 程 结 束 后 调用 。 这 个 委托 方法 接收 内 建 过 程 的 验证 结 
果 ， 其 中 包含 错误 发 生 的 信息 ， 并 和 返回 一 个 布尔 值 ， 表 示 最 终 的 验证 结果 。ServerCertifi 
cateValidationCallback 属性 可 以 用 于 重 写 内 建 的 验证 结果 ， 或 者 执行 附加 的 验证 步骤 。 


在 示例 中 ， 我 们 使 用 这 个 属性 执行 附加 的 验证 步骤 。 只 有 满足 如 下 条 件 时 服务 器 证 书 才 认 
为 是 有 效 的 : 























。 内 建 验证 成 功 ， 即 errors == SslPolicyErrors.None; 
。 证 书 链 至 少 包含 一 个 已 知 的 CA 证 书 (锁定 的 证 书 )。 


请 注意 ， 证 书 链 的 检查 中 跳 过 了 叶 证 书 ， 因 为 我 们 只 需要 确保 CA 证 书 属 于 一 个 已 知 的 
锁定 证 书 集 合 即 可 。 还 要 注意 的 是 ， 这 个 锁定 证 书 集合 只 适用 于 Twitter 上 下 文 。 正 如 
Asset.Throws 所 示 ， 如 果 使 用 这 一 配置 连接 其 他 的 服务 器 (api.github.com)， 会 导致 证 书 
验证 异常 。 

















a 








在 这 本 书 编写 时 ， 证 书 识别 的 使 用 还 是 高 度 依赖 于 上 下 文 ， 通 常 必须 与 管理 服务 器 的 机 构 进 
行 协商 。Twitter 安全 最 佳 实践 就 是 使 用 锁定 证 书 集合 策略 的 一 个 例子 。 但 是 ， 人 们 正在 制定 
一 些 新 的 规范 ， 尝 试 将 这 一 技术 变 得 更 为 通用 。 其 中 一 个 规范 称 为 HTTP 公共 密 钥 锁定 扩展 
(Publick Key Pinning Extension for HTTP)， 这 一 规范 允许 服务 器 告诉 客户 端 在 一 段 指定 时 间 
内 锁定 其 提供 的 证 书 ， 上 有 具体 实现 方法 是 在 响应 标 头 中 加 入 锁定 的 证 书 以 及 锁定 时 间 段 : 











Public-Key-Pins: pin-sha1="4n972HfV354KP560yw4uqe/baXc="; 
pin-sha1="qvTGHdzF6KLavt4P00gs2a6pQ00=" ; 
pin-sha256="LPJNuL+wow4m6DsqxbninhshH lwf pO JecwQzYpOLmCQ=" ; 
max -age=2592000 











对 服务 器 进行 身份 验证 时 ， 你 应 该 强制 实现 的 另 一 个 方面 是 ， 确 保 现 有 的 证 书 没 有 撤 
销 。 但 是 ， 要 实现 这 一 功能 ，ServicePointManager 必须 通过 静态 属性 CheckCertificate 
RevocationList， 有 明确 进行 配置 : 





ServicePointManager .CheckCertificateRevocationList = true; 


NET HTTP 客户 端 基础 结构 使 用 ServicePointManager 类 ， 通 过 ServicePoint 对 象 ， 获 得 
到 服务 器 的 连接 。 

我 们 也 可 以 使 用 WebRequestHandler .ServerCertificateValidationCallback， 确 保 执 行 适当 
的 撤销 验证 。 


return errors == SslPolicyErrors.None && 
caCerts.Any(cert => verisignCerts.Contains(cert.GetCertHashString())) && 
chain.ChainPolicy.RevocationMode == X509RevocationMode.Online; 





以 上 代码 中 的 最 后 一 个 条 件 ， 使 用 了 回调 委托 方法 接收 的 X599Chain 的 ChainPolicy 属性 ， 
确保 撤销 验证 使 用 的 是 在 线 机 制 模式 。 如 果 这 个 条 件 不 为 真 ， 那 么 代码 就 不 接受 这 个 服务 
器 证 书 ， 并 抛 出 一 个 异常 。 








15.3.5 客户 端 身份 验证 

TLS 传输 安全 机 制 也 可 以 提供 客户 端 身 份 验证 ， 但 要 使 用 客户 闯 证 书 ， 增 加 了 客户 端的 复 
杂 度 和 基础 结构 要 求 ， 客 户 端 必须 存储 私有 密 钥 ， 并 需要 向 客户 端 颁发 证 书 。 因 为 这 些 条 
件 要 求 ， 人 们 通常 不 会 进行 TLS 客户 端 身份 验证 。 然 而 ， 在 以 下 场景 中 你 应 该 认真 考虑 使 
用 TLS 客户 端 身份 验证 : 








。 系统 安全 需要 使 用 可 靠 性 更 高 的 客户 端 身份 验证 方式 ; 
。 系统 已 经 具有 PKI (Public Key Infrastructure， 公 和 铀 基础 设施 ) ， 可 用 于 颁发 客户 端 证 书 。 





例如 ， 多 个 欧洲 国家 正在 推行 电子 身份 证 计划 (electronic identity initiatives， 参 见 https:// 
www.eid-stork.eu) ， 让 每 个 公民 拥有 一 张 包含 个 人 证 书 ( 以 及 相关 私 钥 ) 的 智能 卡 。 这 些 
证 书 可 以 用 于 对 公民 与 电子 政务 网 站 的 TLS 交互 进行 身份 验证 。 因 此 ， 如 果 在 这 些 国家 
开发 电子 政务 Web API， 你 就 应 该 考虑 使 用 TLS 客户 端 身份 验证 。 目 前 ， 实 现 TLS 客户 
端 身 份 验证 的 主要 限制 在 于 ， 难 以 在 便携 设备 上 使 用 这 些 只 能 卡 ， 例 如 : 智能 手机 或 平板 
电脑 。 














Windows Azure Service Management REST API 是 一 个 使 用 基于 TLS 的 客户 端 身份 验证 的 公 
共 Web API 的 一 个 具体 例子 。 客 户 端 请 求 必须 使 用 一 个 管理 证 书 ， 该 证 书 预先 与 管理 服务 
进行 了 关联 。 在 这 个 API 中， 客户 端 自 己 生 成 证 书 ， 不 需要 具有 公 钼 基础 设施 ， 从 而 简化 
了 证 书 的 使 用 。 























如 果 在 IIS 上 进行 Web API 托管 ， 你 可 以 在 IIS 管理 器 的 功能 视图 中 ， 选 择 SSL 设置 ， 配 
E TLS 客户 端 身 份 验证 ， 如 图 15-8 Aras. 














@ SSL Settings 
This page lets you modify the SSL settings for the content of a 
Web site or application. 
Require SSL 
Client certificates: 
© Ignore 
© Accept 
@ Require 











图 15-8: 配置 TLS 客户 端 身份 验证 
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这 个 设置 对 一 个 文件 夹 有 效 ， 为 TLS 握手 提供 三 个 选项 : 





。 不 请 求 客户 端 证 书 (Ignore) ; 
。 请 求 客 户 端 证 书 ， 但 允许 客户 端 不 发 送 证 书 (Accept) ; 
。 请 求 客户 端 证 书 ， 并 且 要 求 客 户 端 发 送 证 书 (Require). 








使 用 自 托 管 时 ， 你 可 以 使 用 netsh 命令 行 工具 ， 在 设置 服务 器 TLS 证 书 时 指定 clientcer 
tnegotiation 参数 ， 配 置 客户 端 身份 验证 。 





netsh http add sslcert (...) clientcertnegotiation=enable 
客户 证 书 并 不 包含 在 客户 端 发 送 的 HTTP 请 求 中 ， 而 是 请 求 使 用 的 传输 连接 的 一 个 属性 。 
这 个 证 书 通过 Web API 托管 层 与 请 求 对 象 进行 关联 。 对 于 自 托 管 ， 你 必须 进行 一 个 额外 的 
配置 ， 将 配置 对 象 的 ClientCredentialType 属性 设置 为 Certificate, 











var config = new HttpSelfHostConfiguration("https: //www.example.net:8443"); 
config.ClientCredentialType = HttpClientCredentialType. Certificate; 


进行 这 项 配置 ， 证 书信 息 才 能 从 自 托 管 的 WCE 适配器 向 上 传 到 请 求 对 象 。 这 个 配置 并 不 
影响 TLS 连接 的 协商 和 建立 一 也 就 是 说 ， 这 个 配置 并 不 能 株 代 基于 netsh 的 配置 工作 。 


如 果 你 使 用 的 是 Web 托管 ， 那 么 就 不 需要 进行 这 项 配置 。 








HttpSelfHostConfiguration 也 提供 了 属性 X509CertificateValidator， 以 定义 附加 的 定 
制 证 书 验证 过 程 。 请 注意 ，X569CertificateValidator 属性 不 会 改变 TLS 的 HTTP.SYS 
实现 的 证 书 验证 ， 只 是 增加 了 男 一 个 验证 过 程 。 而 且 ， 只 有 使 用 自 托管 时 ， 才 能 使 用 
X509CertificateValidator 属性 。 

















使 用 基于 TLS 的 客户 端 身份 验证 时 ， 无 论 使 用 何 种 托管 方式 ， 你 都 需要 在 服务 器 端 检 查 协 
商 证 书 ， 以 获得 客户 端的 身份 。 你 可 以 使 用 GetCLientCertificate 扩展 方法 ， 从 请 求 消息 
中 得 到 客户 端 证 书 ， 如 示例 15-1 所 示 。 


示例 15-1: 访问 客户 端 证 书 


public class HelloController : ApiController 





{ 
public HttpResponseMessage Get() 
{ 
var clientCert = Request.GetClientCertificate(); 
var clientName = clientCert == null ? "stranger" : clientCert.Subject; 
return new HttpResponseMessage 
{ 
Content = new StringContent("Hello there, " + clientName) 
}; 
} 
} 


ASP.NET Web API 2.0 中 ， 你 也 可 以 使 用 新 的 HttpRequestContext 类 ， 取 得 客户 端 证 书 : 
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var clientCert = Request.GetRequestContext().ClientCertificate; 


获取 客户 端 证 书 ， 还 有 一 个 更 好 的 方法 ， 是 使 用 如 示例 15-2 中 的 消息 处 理 程序 。 示 例 15-2 











中 的 消息 处 理 程序 将 接收 到 的 客户 端 证 书 映射 到 一 个 基于 声明 的 用 户 标识 。 使 用 这 种 方 





式 ， 不 管 使 用 何 种 身份 验证 机 制 ， 我 们 都 可 以 得 到 统一 格式 的 用 户 标 识 。 我 们 也 可 以 使 用 
这 个 消息 处 理 程 序 ， 执 行 附加 的 证 书 验证 。 在 默认 情况 下 ，TLS 的 HTTPS.SYS 实现 会 使 
用 Windows Store 中 存在 的 任何 受信 任 的 根 证 书 颁 发 机 构 ， 进 行 证 书 验 证 。 但 是 ， 我 们 也 
许 希 望 对 证 书 颁发 机 构 进 行 一 些 限制 。 


示例 15-2: 进行 证 书 验证 和 声明 映射 的 消息 处 理 程序 


public class X509CertificateMessageHandler : DelegatingHandler 





{ 

















private readonly X509CertificateValidator _validator; 

private readonly Func<X509Certificate2, string> _issuerMapper; 

const string X509AuthnMethod = 
"http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/x509"; 


public X509CertificateMessageHandler ( 
X509CertificateValidator validator, 
Func<X509Certificate2,string> issuerMapper ) 


_validator = validator; 
_issuerMapper = issuerMapper ; 


} 


protected override async Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, 
CancellationToken cancellationToken) 


var cert = request.GetClientCertificate(); 

if (cert == null) return await base.SendAsync(request, cancellationToken) ; 
try 

{ 


} 


catch (SecurityTokenValidationException) 


{ 
} 


var issuer = _issuerMapper(cert); 
if (issuer == null) 


{ 
} 


_validator .Validate(cert); 


return new HttpResponseMessage(HttpStatusCode.Unauthorized) ; 


return new HttpResponseMessage(HttpStatusCode. Unauthorized) ; 


var claims = ExtractClaims(cert, issuer); 
var identity = new ClaimsIdentity(claims, X509AuthnMethod) ; 
AddIdentityToCurrentPrincipal(identity, request); 


return await base.SendAsync(request, cancellationToken) ; 
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private static IEnumerable<Claim> ExtractClaims( 
X509Certificate2 cert, 
string issuer) 


{ 
} 


private static void AddIdentityToCurrentPrincipal(ClaimsIdentity identity) 


{ 


} 
} 





首先 ， 这 个 消息 处 理 程序 使 用 GetclientCertificate 扩展 方法 ， 从 请 求 消息 中 获得 客户 
端 证 书 ， 然 后 使 用 构造 函数 中 定义 的 验证 程序 ， 执 行 附加 的 证 书 验证 。x5e9certificate 
Validator 是 NET 框架 提供 的 一 个 抽象 基 类 ， 表 示 一 个 证 书 验证 过 程 ， 其 中 定义 了 一 组 静 
态 方法 ， 进 行 常见 的 验证 操作 。 























public abstract class X509CertificateValidator : ICustomIdentityConfiguration 
{ 

// 省 略 类 成 员 及 实现 

public static X509CertificateValidator None {get{...}} 

public static X509CertificateValidator PeerTrust {get{...}} 

public static X509CertificateValidator ChainTrust {get{...}} 

public static X509CertificateValidator PeerOrChainTrust{get{...}} 
} 





























如 果 证 书 通过 了 附加 的 验证 ， 那 么 消息 处 理 程 序 就 使 用 Func<xs509Certificate2, string>, 
获得 证 书 颁发 者 的 名 称 ， 用 于 创建 获取 的 声明 。 获 得 证 书 颁发 者 的 名 称 常用 的 两 个 策略 为 : 











© 使 用 证 书 颁发 者 的 名 称 (例如 : CN=Demo Certification Authority, 0=Web API Book) ; 
。 使 用 预先 定义 的 注册 表 ， 将 颁发 客户 端 证 书 的 CA 证 书 映射 到 一 个 证 书 颁发 者 字符 串 。 


.NET 框架 提供 一 个 IssuerNameRegistry 类 ， 实 现 上 面 列 出 的 第 二 种 策略 。 








获得 证 书 颁发 者 名 称 之 后 ， 消 息 处 理 程序 从 客户 端 证 书 计 算出 表示 请 求 者 的 声明 集合 。 





private static IEnumerable<Claim> ExtractClaims( 
X509Certificate2 cert, 
string issuer) 


var claims = new Collection<Claim> 
{ 
new Claim(ClaimTypes.Thumbprint, 
Convert. ToBase64String(cert.GetCertHash()), 
ClaimValueTypes.Base64Binary, issuer), 

new Claim(ClaimTypes.X500DistinguishedName, 
cert.SubjectName.Name, 
ClaimValueTypes.String, issuer), 

new Claim(ClaimTypes.SerialNumber, cert.SerialNumber, 
ClaimValueTypes.String, issuer), 
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new Claim(ClaimTypes.AuthenticationMethod, X509AuthnMethod, 
ClaimValueTypes.String, issuer) 


}; 


var email = cert.GetNameInfo(X509NameType.EmailName, false); 
if (email != null) 


{ 


} 


claims.Add(new Claim(ClaimTypes.Email, email, 


ClaimValueTypes.String, issuer)); 


return claims; 


} 





在 这 段 代 码 中 ， 我 们 将 多 个 证 书 字段 各 自 映 射 到 单独 的 声明 对 象 ， 即 : 证 书 散 列 指纹 、 主 





体 名 称 、 证 书 序列 号 以 及 主体 的 邮件 地 址 (如果 存在 的 话 )， 还 添加 了 一 个 表明 身份 验证 
方法 的 声明 对 象 。 


最 后 ， 消 息 处 理 程序 创建 了 一 个 声明 标识 ， 将 其 加 入 当前 的 基于 声明 的 用 户 对 象 。 如 果 当 
前 用 户 对 象 不 存在 ， 就 创建 一 个 新 的 当前 用 户 对 象 。 


























private static void AddIdentityToCurrentPrincipal(ClaimsIdentity identity) 


{ 


private void AddIdentityToCurrentPrincipal( 


} 


ClaimsIdentity identity, 
HttpRequestMessage request) 


var principal = request.GetRequestContext().Principal as ClaimsPrincipal; 
if (principal == null) 


{ 
principal = new ClaimsPrincipal(identity) ; 
request.GetRequestContext().Principal = principal; 
} 
else 
{ 
principal.AddIdentity(identity) ; 
} 











使 用 消息 处 理 程序 ， 将 客户 端 证 书 映射 为 一 个 基于 声明 的 用 户 身份 ， 下 游 的 Web API 
运行 时 组 件 就 可 以 总 是 以 不 变 的 方式 使 用 用 户 身 份 信息 。 例 如 ， 前 面 的 示例 15-1 中 的 
HelloController 现在 可 以 重新 进行 实现 ， 代 码 如 下 : 























public class HelloController : ApiController 


{ 


public HttpResponseMessage Get() 


{ 


var principal = User as ClaimsPrincipal; 
var name = principal 

.Identities.SelectMany(ident => ident.Claims) 

.FirstOrDefault(c => c.Type == ClaimTypes.Email).Value ?? "stranger"; 
return new HttpResponseMessage 


{ 





Content = new StringContent("Hello there, " + name) 


}5 
} 


45 ASP.NET MVC 的 做 法 相似 ，ApiControltter 类 提供 一 个 属性 User， 保 存 请 求 者 的 用 户 

对 象 。 还 需要 注意 的 是 ， 使 用 用 户 身份 的 代码 只 需要 处 理 声 明 ， 不 必 依 赖 基于 传输 的 客户 

a 举 个 例子 ， 如 果 客 户 端 使 用 Te N: an 9 HR BE IP ARS EF Bt 

验证 机 制 ， 消 息 处 理 程序 的 操作 代码 也 无 需 进行 修改 。 但 是 ， 在 接着 介绍 基于 消息 的 身份 
验证 之 前 ， 我 们 必须 了 解 客户 端 如 何 使 用 基于 传输 的 客户 端 身份 验证 。 




















在 客户 端 一 方 ， 如 果 使 用 基于 TLS 的 身份 验证 配置 ， 你 必须 直接 处 理 第 14 章 中 介绍 的 
HttpClient 处 理 程序 之 一 : HttpClientHandler 或 WebRequestHandler , 


























如 果 使 用 第 一 个 选项 ， 你 需要 明确 配置 HttpCLient 使 用 HttpClientHanlder 实例 ， 并 将 
HttpCLientHanLder 的 属性 ClientCertificateOptions ix A Automatic, 


var client = new HttpClient( 
new HttpClientHandler{ 
ClientCertificateOptions = ClientCertificateOption. Automatic 
}) 
ED cess 


由 此 生成 的 HttpClient 接着 就 可 以 正常 使 用 : 如 果 在 连接 握手 过 程 中 ， 服 务 器 要 求 客 户 端 
提供 证 书 ，HttpClientHandler 实例 就 会 自动 选择 一 个 兼容 的 客户 端 证 书 。Windows Store 
应 用 程序 只 能 使 用 HttpClientHandler 。 























对 于 经 典 场景 〈 例 如 : 控制 台 程 序 、WinForm 程序 或 WPF 应 用 程序 ) ， 我 们 还 有 第 二 个 选 
项 : 使 用 WebRequestHandler , 


a 


var clientHandler = new WebRequestHandler() 
clientHandler.ClientCertificates.Add(cert); 
var client = new HttpClient(clientHandler) 





在 这 段 代 码 中 ，cert 是 一 个 X509Certificate2 实例 ， 表 示 客 户 端 证 书 。 这 个 cert 实例 可 
以 直接 从 一 个 PFX 文件 构建 或 者 从 Windows 的 证 书库 中 得 到 。 








X509Store store = null; 

try 

{ 
store = new X509Store(StoreName.My, StoreLocation.CurrentUser ); 
store.Open(OpenFlags.OpenExistingOnly | OpenFlags.ReadOnly) ; 
// 从 store.Certificates 选择 证 书 ……: 








finally 
{ 


if(store != null) store.Close(); 





在 讨论 了 如 何 使 用 传输 安全 机 制 提 供 客 户 端 和 服务 器 身份 验证 之 后 ， 我 们 现在 要 了 解 如 何 
在 HTTP 消息 层 解决 这 些 安全 需求 。 








15.3.6 ee ee 

我 们 在 第 1 章 中 介绍 过 ，HTTP 协议 规范 定义 了 一 个 通用 的 身份 验证 框架 ， 在 这 个 框架 之 
te a RFC 2617 中 定义 的 基础 认证 和 摘要 认证 方案 就 属于 这 种 
身份 验证 机 制 。 ee 以 及 一 个 质询 - 响应 
序列 ， 供 有 具体 的 身份 验证 机 制 使 用 (参见 第 1 章 和 附录 E). 


基础 认证 方案 使 用 一 个 简单 的 用 户 名 和 密码 对 ， 对 客户 端 进行 身份 验证 。 这 些 身 份 信息 以 

如 下 方式 加 入 请 求 消息 中 : 

(1) 连接 用 户 名 和 密码 ， 使 用 : (冒号 ) 分 隔 符 ; 

(2) 使 用 Base64 对 连接 串 进 行 编码 ， 生 成 的 字符 串 放 置 在 Authorization 标 头 的 方案 标识 
符 Basic 之 后 。 


示例 15-3 中 的 代码 使 用 基础 认证 从 GitHub API 获得 用 户 信 息 。 请 注意 ， 代 码 给 请 求 消息 
加 入 了 Authorization 标 头 。 


























示例 15-3: 使 用 基础 认证 从 GitHub 获得 用 户 信息 


using (var client = new HttpClient()) 


var req = new HttpRequestMessage( 
HttpMethod.Get, "https://api.github.com/user"); 
req.Headers.UserAgent.Add(new ProductInfoHeaderValue("webapibook","1.0")); 
req.Headers.Authorization = new AuthenticationHeaderVaLue( 
"Basic", 
Convert. ToBase64String( 
Encoding.ASCII.GetBytes(username + 


+ password) ) 
); 

var resp = await client.SendAsync(req); 

Console.WriteLine(resp.StatusCode) ; 

var cont = await resp.Content.ReadAsStringAsync(); 

Console.WriteLine(cont) ; 


} 


在 服务 器 端 ， 我 们 可 以 使 用 如 示例 15-4 中 的 消息 处 理 程序 ， 强 制 使 用 基础 认证 。 示 例 15-4 
中 的 消息 处 理 程 序 检查 请 求 消息 中 是 否 存在 带 有 Basic 方案 的 Authorization pk, FFA 
试 获取 用 户 名 和 密码 ， 进 行 验 证 。 如 果 验 证 通过 ， 消 息 处 理 程 序 就 生成 一 个 描述 请 求 者 的 
用 户 对 象 ， 将 其 添加 到 请 求 上 下 文 ， 然 后 将 消息 处 理 委 托 给 下 一 个 处 理 程 序 。 如 果 这 些 条 
件 中 任何 一 个 失败 ， 那 么 消息 处 理 程序 会 产生 一 个 状态 码 为 401 的 响应 消息 ， 终 止 请 求 的 
处 理 。 




























































































如 果 响 应 消息 的 状态 码 为 491， 那么 处 理 程序 会 给 响应 消息 加 入 一 个 WWW-Authenticate 标 
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头 ， 其 中 包含 所 需 的 身份 验证 方案 和 域名 。 
示例 15-4: 基础 认证 消息 处 理 程序 


public class BasicAuthenticationDelegatingHandler : DelegatingHandler 

{ 
private readonly Func<string, string, Task<ClaimsPrincipal>> _validator; 
private readonly string _realm; 


public BasicAuthenticationDelegatingHandler(string realm, Func<string, string, 
Task<ClaimsPrincipal>> validator) 

{ 
_validator = validator; 
_realm = "realm=" + realm; 


} 


protected async override Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, 
CancellationToken cancellationToken) 


{ 
HttpResponseMessage res; 
if (!request.HasAuthorizationHeaderWithBasicScheme()) 
{ 
res = await base.SendAsync(request, cancellationToken); 
} 
else 
{ 
var principal = await 
request. TryGetPrincipalFromBasicCredentialsUsing(_validator) ; 
if (principal != null) 
{ 
request.GetRequestContext().Principal = principal; 
res = await base.SendAsync(request, cancellationToken) ; 
} 
else 
{ 
res = request.CreateResponse(HttpStatusCode.Unauthorized) ; 
} 
} 
if (res.StatusCode == HttpStatusCode.Unauthorized) 
: res.Headers.WwwAuthenticate.Add( 
new AuthenticationHeaderValue("Basic", _realm)); 
} 
return res; 
} 


} 


如 果 身 份 验证 通过 ， 那 么 产生 的 用 户 对 象 就 通过 HttpRequestContext.Principal 属性 ， 添 
加 到 请 求 上 下 文 。 用 户 对 象 的 获取 和 验证 是 通过 一 个 扩展 方法 完成 的 ， 该 方法 定义 如 下 : 





public static async Task<ClaimsPrincipal> 
TryGetPrincipalFromBasicCredentialsUsing( 





this HttpRequestMessage req, 
Func<string, string, Task<ClaimsPrincipal>> validate) 


string pair; 
try 


{ 
pair = Encoding.UTF8.GetString( 


Convert.FromBase64String(req.Headers.Authorization.Parameter)); 


} 


catch (FormatException) 


{ 


return null; 


catch (ArgumentException) 


{ 


return null; 


} 

var ix = pair.IndexOf(':'); 

if (ix == -1) return null; 

var username = pair.Substring(0, ix); 
var pw = pair.Substring(ix + 1); 
return await validate(username, pw); 


} 
这 个 方法 使 用 构造 函数 中 传人 的 委托 方法 进行 用 户 名 和 密码 验证 ， 与 具体 验证 逻辑 无 关 。 


15.3.7 ”实现 基于 HTTP 的 身份 验证 

在 前 面 的 示例 中 ， 我 们 使 用 Web API 消息 处 理 程序 ， 实 现 了 服务 器 端的 HTTP 身份 验证 。 
然而 ， 我 们 还 可 以 使 用 别 的 架构 选项 使 用 Web API 筛选 器 ， 在 管道 中 实现 身份 验证 ; 或 
者 在 托管 层 进行 身份 验证 。 接 下 来 我 们 将 讨论 不 同 选 项 的 利 商 。 























ARTE Web API 饰 选 器 上 实现 身份 验证 ， 你 可 以 访问 更 多 的 请 求 信 息 ， 其 中 有 : 


。 所 选 的 控制 器 和 路 由 ， 
。 路 由 参数 ; 
。 操作 参数 《如果 使 用 操作 筛选 器 ) o 


如 果 你 的 身份 验证 逻辑 依赖 这 些 信息 ， 就 可 以 使 用 Web API 筛选 器 实现 身份 验证 。 而 且 .， 
Web API 和 饰 选 器 还 可 以 选择 性 地 应 用 于 一 部 分 控制 器 或 者 操作 。 
但 是 ， 在 饰 选 器 层 进 行 身份 验证 也 有 一 些 很 严重 的 缺点 。 


首 后 端 才能 检测 到 未 经 认证 的 请 求 ， 增 加 了 拒绝 请 求 的 计算 开销 。 

后 端 才 能 使 用 请 求 者 的 身份 信息 。 这 意味 着 其 他 的 中 间 层 组 件 ， 如 缓存 中 间 件 ， 
无 法 访问 这 些 身 份 信息 。 如 果 使 用 私有 缓存 〈 即 : 按 用 户 进行 缓存 )， 那 么 这 种 方 
产生 严重 的 限制 。 
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另外 一 个 选项 是 ， 在 消息 处 理 程序 层 实 现 身 份 验证 功能 ， 我 们 之 前 就 是 使 用 的 这 种 方式 。 
消息 处 理 程序 在 托管 适 配 层 之 后 立刻 运行 ， 因 此 拒绝 请 求 的 开销 会 比较 小 。 而 且 ， 之 后 的 
所 有 处 理 程序 都 可 以 使 用 请 求 者 的 身份 信息 。 如 果 你 使 用 HttpCLient， 消 息 处 理 程序 在 客 
户 端 也 可 使 用 ， 因 此 这 种 方式 使 得 系统 呈现 一 种 有 趣 的 对 称 性 。 














然而 ，OWIN 规范 (参见 第 11 章 ) 的 使 用 ， 引 入 了 实现 身份 验证 的 另 一 个 选项 : OWN 
中 间 件 。 这 种 方式 有 一 些 重要 的 优点 。 





。 扩展 了 使 用 范围 。 同 一 个 身份 验证 中 间 件 可 以 由 多 个 框架 使 用 ， 不 仅仅 限于 ASP.NET 
Web API。 
。 下 游 的 OWIN 中 间 件 ， 例 如 : 缓存 或 日 志 ， 立 即 可 以 使 用 请 求 者 的 身份 信息 。 


事实 上 ，OWIN 规范 的 引入 意味 着 ， 所 有 不 与 框架 相关 的 中 间 层 都 最 好 实现 为 OWIN 中 间 
fF. Katana 项 目 遵循 的 就 是 这 种 方式 ， 提 供 了 一 组 身份 验证 中 间 件 的 实现 。 





显然 ， 只 有 在 OWIN 服务 器 上 进行 Web API 托管 时 ， 你 才能 够 使 用 这 种 方式 。 但 是 ， 随 
着 人 们 越 来 越 多 地 采纳 OWIN 规范 ， 这 种 方式 也 会 变 得 更 为 普遍 。 


15.3.8 Katana 身份 验证 中 间 件 

Katana 项 目 2.0 包含 一 组 中 间 件 实现 ， 提 供用 于 不 同 范围 的 多 种 身份 验证 机 制 ， 从 传统 的 
基于 cookie 的 身份 验证 到 基于 OAuth 2.0 的 身份 验证 。 这 些 中 间 件 的 实现 基于 一 个 可 扩展 
的 类 结构 ， 我 们 接 下 来 要 对 进行 介绍 。 








这 个 类 结构 的 根 是 基础 抽象 类 AuthenticationMiddleware<Toption> (参见 示例 15-5), A 
体 的 身份 验证 中 间 件 可 以 对 这 个 基 类 进行 派生 。 


示例 15-5: 身份 验证 中 间 件 基础 类 
public abstract class AuthenticationMiddleware<TOptions> : OwinMiddleware 
where TOptions : AuthenticationOptions 


{ 
protected AuthenticationMiddleware(OwinMiddleware next, TOptions options) 
: base(next) 
fase F 


public TOptions Options { get; set; } 


public override async Task Invoke(IOwinContext context) 
{ 
AuthenticationHandler<TOptions> handler = CreateHandler(); 
await handler.Initialize(Options, context); 
if (!await handler .InvokeAsync()) 
{ 


await Next.Invoke(context) ; 


await handler .TeardownAsync(); 
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} 


protected abstract AuthenticationHandler<TOptions> CreateHandler(); 


} 


这 个 类 有 一 个 类 型 参数 Toption， 定 义 了 身份 验证 中 间 件 的 配置 选项 ， 如 身份 验证 。 通 党 
情况 下 ， 开 发 定制 的 身份 验证 中 间 件 需要 定义 一 个 具体 的 选项 类 ， 示 例 15-6 就 定义 了 这 样 
一 个 选项 类 。 


示例 15-6: 基础 认证 选项 
public class BasicAuthenticationOptions : AuthenticationOptions 


{ 
public Func<string, string, Task<AuthenticationTicket>> 
ValidateCredentials { get; private set; } 
public string Realm { get; private set; } 


public BasicAuthenticationOptions( 
string realm, 
Func<string, string, Task<AuthenticationTicket>> validateCredentials) 
: base("Basic") 


Realm = realm; 
ValidateCredentials = validateCredentials; 


} 


当中 间 件 管道 处 理 请 求 时 ， 会 调用 OwinMiddleware. Invoke 方法 ， 将 身份 验证 操作 委托 给 
由 CreateHandler 方法 提供 的 一 个 身份 验证 处 理 程序 实例 。 因 此 ， 定 制 身份 验证 中 间 件 的 
主要 任务 通常 就 是 定义 这 个 CreateHandler 方法 (参见 示例 15-7)。 


























示例 15-7: 基础 认证 中 间 件 
class BasicAuthnMiddleware : AuthenticationMiddleware<BasicAuthenticationOptions> 
{ 
public BasicAuthnMiddleware( 
QOwinMiddleware next, 
BasicAuthenticationOptions options) 
: base(next, options) 


{} 


protected override AuthenticationHandler<BasicAuthenticationOptions> 
CreateHandler() 
{ 


} 


return new BasicAuthenticationHandler (Options) ; 
} 
了 解 基础 中 间 件 如 何 使 用 这 个 处 理 程 序 ， 可 以 帮助 你 更 好 地 理解 处 理 程序 的 工作 。 如 


处 
示例 15-5 所 示 ， 基 础 中 间 件 的 Invoke 方法 在 创建 处 理 程 序 之 后 ， 执 行 了 三 项 任务 。 首 
先 ，Invoke 方法 调用 了 处 理 程 序 的 Initialize 方法 。 我 们 稍 后 会 看 到 ， 处 理 程 序 的 这 



























































个 Initialize 方 法 触发 了 大 部 分 的 身份 验证 操作 。 随 后 ，Invoke 方法 调用 了 处 理 程序 
的 InvokeAsync 方法 。 如 果 InvokeAsync 方法 返回 false， 那 么 Invoke 方法 会 调用 下 一 个 
中 间 件 ， 否 则 Invoke 方法 会 终止 请 求 处 理 ， 也 就 是 说 不 再 调用 下 游 的 中 间 件 。 最 后 ， 在 
Invoke 方法 调用 TeardownAsync 方法 ， 释 放 处 理 程序 实例 。 请 注意 ， 中 间 件 和 处 理 程序 对 
象 的 生存 期 不 同 : 中 间 件 存在 于 整个 应 用 程序 过 程 中 ， 而 处 理 程序 实例 只 存在 于 单个 请 求 
处 理 过 程 。 这 也 是 中 间 件 和 处 理 程序 程序 作为 两 个 单独 概念 存在 的 原因 之 一 。 























抽象 类 AuthenticationHanlder 提供 了 大 部 分 通用 的 的 身份 验证 协调 功能 ， 有 具体 的 身份 验 
证 逻辑 则 委托 给 由 具体 的 派生 类 实现 的 挂钩 方法 。 对 于 基于 HTTP 框架 的 身份 验证 ， 有 两 
个 挂钩 方法 尤为 重要 : AuthenticateCoreAsync 和 ApplyResponseChallengeAsync, 
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AuthenticateCoreAsync 方法 由 处 理 程序 的 Initialize 方法 调用 ， 对 当前 请 求 进行 身份 验 
证 。 示 例 15-8 中 实现 的 AuthenticateCoreAsync 方法 ， 尝 试 从 请 求 的 Authorization 标 头 
获得 Basic 身份 信息 进行 验证 。 如 果 验 证 通过 ，AuthenticateCoreAsync 方法 返回 一 个 用 户 
身份 ， 由 基 类 的 Initialize 方法 添加 到 请 求 一 一 具体 地 说 ， 是 添加 到 上 下 文 条 目 server. 
User 。 如 果 验 证 失败 ，AuthenticateCoreAsync 方法 返回 nutL， 说 明 身 份 验证 没有 通过 。 





处 理 程 序 的 Initialize 方 法 将 ApplyResponseChallengeAsync 方 法 注册 到 响应 事件 
OnsendingHeaders， 这 一 事件 在 响应 的 标 头 开始 发 送 之 前 触发 。 示 例 15-8 中 实现 的 Apply 








ResponseChallengeAsync， 在 响应 状态 码 为 491 时 ， 给 响应 添加 一 个 WWW-Authenticatae 质 
询 标 头 ， 其 中 包含 Basic 认证 方案 。 





示例 15-8: 基础 认证 处 理 程序 
class BasicAuthenticationHandler : AuthenticationHandler<BasicAuthenticationOptions> 


{ 


private readonly string _challenge; 


public BasicAuthenticationHandler(BasicAuthenticationOptions options) 


{ 
_challenge = "Basic realm=" + options.Realm; 
} 
protected override async Task<AuthenticationTicket> AuthenticateCoreAsync() 
{ 
var authzValue = Request.Headers.Get("Authorization"); 
if (string.IsNuLlOrEmpty(authzValue) || !authzValue.StartsWith("Basic ", 
StringComparison.OrdinalIgnoreCase) ) 
{ 
return null; 
} 
var token = authzValue.Substring("Basic ".Length).Trim(); 
return await 
token. TryGetPrincipalFromBasicCredentialsUsing( 
Options.ValidateCredentials); 
} 
protected override Task ApplyResponseChallengeAsync( ) 
{ 
if (Response.StatusCode == 401) 
{ 
var challenge = Helper.LookupChallenge( 
Options.AuthenticationType, Options.AuthenticationMode) ; 
if (challenge != null) 
{ 
Response.Headers.AppendValues("WWW-Authenticate", _challenge); 
} 
} 
return Task.FromResult<object>(null); } 
} 


} 


异步 挂钩 方法 AuthenciationTicket 返回 值 为 AuthenticationTicket 类 型 ， 这 是 Katana 项 
目 进入 的 一 个 新 类 型 ， 用 于 表示 用 户 身份 。AuthenticationTicket 类 包含 一 个 声明 身份 和 
一 组 身份 验证 属性 。 








public class AuthenticationTicket 
{ 
public AuthenticationTicket( 
ClaimsIdentity identity, AuthenticationProperties properties) 
{ 
Identity = identity; 
Properties = properties; 
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} 


public ClaimsIdentity Identity { get; private set; } 
public AuthenticationProperties Properties { get; private set; } 


} 


为 了 实现 中 间 件 注册 ， 定 制 的 身份 验证 中 间 件 通常 也 提供 一 个 如 示例 15-9 所 示 的 扩展 方 
法 ， 以 使 用 如 下 代码 : 


app.UseBasicAuthentication( 
new BasicAuthenticationOptions("webapibook", (un, pw) => { 
/* 身份 验证 逻辑 */ 

pi 


示例 15-9: 用 于 注册 基础 认证 中 间 件 的 扩展 方法 
public static class BasicAuthnMiddlewareExtensions 


{ 
public static IAppBuilder UseBasicAuthentication( 
this IAppBuilder app, BasicAuthenticationOptions options) 





{ 


} 
} 


15.3.9 主动 和 被 动 的 身份 验证 中 间 件 

在 OWIN 规范 中 ， 中 间 件 在 请 求 到 达 Web 框架 之 前 对 其 进行 访问 。 也 就 是 说 ， 在 中 间 件 
运行 时 ， 可 能 还 不 知道 具体 的 身份 验证 要 求 。 假 设 我 们 有 一 个 经 典 的 Web 应 用 程序 以 及 一 
个 托管 在 同一 OWIN 宿主 上 的 Web API, Web 应 用 程序 可 能 使 用 cookie 和 基于 表单 的 身 
份 验 证 ， 而 Web API 可 能 使 用 基础 认证 。 如 果 对 Web API 请 求 错误 地 使 用 了 cookie 进行 
身份 验证 ， 那 么 可 能 会 导致 安全 问题 ， 例 如 CSRF (Cross-Site Request Forgery， 跨 站 请 求 
伪造 ) ， 因 为 cookie 是 由 基于 浏览 器 的 用 户 代理 自动 发 送 的 。 


return app.Use(typeof(BasicAuthnMiddleware), options); 












































Atk, Katana 引入 了 主动 和 被 动身 份 验证 模式 的 概念 。 如 果 使 用 主动 (active) 模式 ， 身 
份 验证 中 间 件 会 主动 地 尝试 对 请 求 进行 身份 验证 ， 如 果 验 证 成 功 就 将 身份 信息 加 入 请 求 上 
下 文 。 如 果 响 应 状态 码 为 491， 身 份 验证 中 间 件 还 会 给 响应 加 入 质询 信息 。 另 一 方面 ， 处 
于 被 动 (passive) 模式 的 中 间 件 只 是 将 自己 注册 到 一 个 身份 验证 管理 器 (authentication 
manager)。 只 有 当 明 确 得 到 调用 时 ， 身 份 验证 处 理 程序 才 会 尝试 对 请 求 进行 身份 验证 并 生 
成 身份 信息 。 只 有 当 身 份 验证 管理 器 对 其 进行 明确 调用 时 ， 处 于 被 动 模式 的 身份 验证 中 间 
件 才 会 给 响应 加 入 质询 信息 。 





















































身份 验证 管理 器 也 是 Katana 引入 的 一 个 新 概念 。 身 份 验 证 管理 器 定义 了 一 个 接口 ， 甚 他 
组 件 (An Web 应 用 程序 ) 可 以 通过 这 个 接口 于 身份 验证 中 间 件 进行 交互 。 在 下 一 市 介绍 
Web API 的 身份 验证 筛选 器 时 ， 我 们 会 介绍 使 用 身份 验证 管理 器 的 具体 例子 。 
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属性 AuthenticationOptions.AuthenticationMode 定义 了 身份 验证 中 间 件 的 操作 模式 。 身 
份 验证 中 间 件 的 大 部 分 实现 并 不 需要 知道 这 个 身份 验证 模式 ， 主 动 和 被 动 模式 的 行为 差异 
是 由 基 类 AuthenticationHandler 中 的 通用 代码 导致 的 。 例 如 ， 只 有 当 身 份 验证 模式 为 主 
动 模式 时 ， 基 类 才 会 调用 AuthenticateCoreAsync 方法 。 





这 条 规则 有 一 个 例外 : 给 响应 添加 质询 信息 。 不 管 配置 的 身份 验证 模式 是 什么 ， 基 础 结构 
总 是 会 调用 ApplyResponseChallengeAsync 方法 。 但 是 ， 只 有 当 身 份 验证 模式 为 主动 模式 ， 
或 者 认证 方案 已 加 入 身份 验证 管理 器 时 ，ApplyResponseChallengeAsync 方法 才 应 该 添加 质 
询 信 息 。 





示例 15-8 中 的 ApplyResponseChallengeAsync 方法 使 用 了 工具 方法 Helper .LookupChallenge， 
以 判断 是 否 应 该 添加 质询 信息 。 


15.3.10 Web API| 身 份 验证 筛选 器 


如 前 所 述 ， 我 们 可 以 选择 将 身份 验证 操作 放 在 Web API 筛选 器 中 。Web API 2.0 进入 了 一 
个 新 的 操作 管道 阶段 ， 专 门 用 于 身份 验证 处 理 。 这 个 阶段 由 身份 验证 筛选 器 组 成 ， 在 授权 
筛选 器 阶段 之 前 执行 ， 也 就 是 说 ， 身 份 验证 筛选 器 阶段 是 操作 管道 的 第 一 个 阶段 。 


身份 验证 筛选 器 接口 包含 两 个 异步 方法 ， 定 义 如 下 : 








public interface IAuthenticationFilter : IFilter 
{ 

Task AuthenticateAsync( 
HttpAuthenticationContext context, 
CancellationToken cancellationToken) ; 

Task ChallengeAsync( 
HttpAuthenticationChallengeContext context, 
CancellationToken cancellationToken) ; 


} 


身份 验证 管道 阶段 分 为 两 段 : 请 求 处 理 和 响应 处 理 。 在 请 求 处 理 中 ，Web API 运行 时 调用 
每 个 已 注册 的 身份 验证 筛选 器 的 AuthenticateAsync 方法 ， 传 人 身份 验证 上 下 文 参数 ， 其 
中 包含 了 操作 上 下 文 和 当前 请 求 。 









































public class HttpAuthenticationContext 
{ 
public HttpActionContext ActionContext { get; private set; } 
public IPrincipal Principal { get; set; } 
public IHttpActionResuLlt ErrorResult { get; set; } 
public HttpRequestMessage Request { get { ... }} 


} 


49-7 EFAJ AuthenticateAsync 方法 负责 对 上 下 文中 的 请 求 进行 身份 验证 。 如 果 请 求 消 
息 中 没有 适当 身份 验证 方案 的 身份 信息 ， 那 么 筛选 器 不 会 修改 上 下 文 。 如 果 身 份 信息 存在 
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而 且 有 效 ， 那 么 筛选 器 会 将 上 下 文 的 Principal 属性 设置 为 通过 身份 验证 的 用 户 对 象 ， 如 
果 身 份 信息 无 效 ， 那 么 上 下 文 的 ErrorResult 属性 会 设置 为 一 个 状态 码 为 401 的 响应 消息 ， 
告诉 运行 时 发 生 了 一 个 身份 验证 错误 ， 因 此 请 求 处 理 阶 段 会 立即 终止 ， 运 行 时 不 再 接着 调 
用 AuthenticateAsync 方法 ， 而 是 开始 响应 处 理 阶段 。 





























如 果 没 有 筛选 器 对 上 下 文 的 ErrorResult 赋值 ， 那 么 运行 时 会 继续 进行 到 下 一 个 管道 阶段 ， 
无 论 上 下 文 的 用 户 对 象 是 否 得 到 赋值 ， 这 就 将 是 否 授权 匿名 请 求 留 给 了 上 层 决定 。 

















当 响 应 从 上 层 返回 ， 或 者 身份 验证 得 选 器 生成 一 个 错误 响应 时 ， 身 份 验证 阶段 的 响应 处 理 
段 就 开始 了 。 在 这 个 响应 段 ， 运 行 时 调用 每 个 已 登记 的 身份 验证 筛选 器 的 ChallengeAsync 
方法 ， 并 传人 一 个 质询 上 下 文 (challenge context), 








public class HttpAuthenticationContext 
{ 
public HttpActionContext ActionContext { get; private set; } 
public IPrincipal Principal { get; set; } 
public IHttpActionResuLlt ErrorResult { get; set; } 
public HttpRequestMessage Request { get { ... }} 
// 省 略 成 员 和 定义 
} 


身份 验证 筛选 器 可 以 借 此 机 会 检查 结果 信息 ， 如 果 需 要 还 可 以 加 入 认证 质询 信息 。 请 注 
意 ， 无 论 在 身份 验证 阶段 的 请 求 处 理 段 发 生 了 什么 ， 运 行 时 总 是 会 调用 所 有 身份 验证 得 选 
器 的 ChaLLengeAsync 方法 . 




















示例 15-10 实现 了 一 个 使 用 基础 认证 方案 的 身份 验证 筛选 器 。 因 为 身份 验证 过 程 
可 能 需要 于 外 部 系统 进行 通信 (例如 : 用 户 身 份 数 据 库 )， 我 们 使 用 了 一 个 返回 
Task<ClaimsPrincipal> 的 国 数 。 如 果 请 求 消 息 中 不 存在 Authorization 标 头 ， 或 者 认证 
方案 不 是 Basic, ISA AuthenticateAsync 方法 不 会 修改 上 下 文 。 如 果 用 户 身份 信息 存在 
但 却 无 效 ， 那 么 AuthenticateAsync 方 法 会 将 ErrorResult 赋值 为 UnauthoritzedResutLt， 
代表 一 个 状态 为 401 的 响应 。UnauthorizedResult 的 质询 列表 为 空 ， 因 为 质询 信息 会 
ChallengeAsync 方法 在 响应 处 理 阶 段 添 加 。 



























































ChallengeAsync 只 是 检查 响应 状态 是 否 为 491， 如 果 是 则 添加 合适 的 质询 信息 。 我 们 必 
须 使 用 帮助 方法 ActionResuLtDetLegate， 因 为 上 下 文 的 Response 属性 的 类 型 是 IHttp 
ActionResult 接口 ， 而 不 是 直接 的 HttpResponse 类 。 帮 助 方法 ActionResultDelegate 可 以 
将 一 列 IHttpActionResult 实例 组 合成 一 个 。 














示例 15-10: 基础 认证 消息 处 理 程 序 
public class BasicAuthenticationFilter : IAuthenticationFilter 
{ 
private readonly Func<string, string, Task<ClaimsPrincipal>> _validator; 
private readonly string _realm; 
public bool AllowMultiple { get { return false; } } 
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public BasicAuthenticationFilter ( 

string realm, Func<string, string, Task<ClaimsPrincipal>> validator) 
{ 

_validator = validator; 

_realm = "realm=" + realm; 


} 


public async Task AuthenticateAsync( 
HttpAuthenticationContext context, 
CancellationToken cancellationToken) 


{ 
var req = context.Request; 
if (req.HasAuthorizationHeaderWithBasicScheme() ) 
{ 
var principal = await 
req. TryGetPrincipalFromBasicCredentialsUsing(_validator) ; 
if (principal != null) 
context.Principal = principal; 
} 
else 
// 质询 信息 将 由 ChallengeAsync 添加 
context.ErrorResult = new UnauthorizedResult( 
new AuthenticationHeaderVaLlue[0], context.Request); 
} 
} 
} 


public Task ChallengeAsync( 
HttpAuthenticationChallengeContext context, 
CancellationToken cancellationToken) 


context.Result = new ActionResultDelegate(context.Result, async (ct, next) => 


{ 


var res = await next.ExecuteAsync(ct); 
if (res.StatusCode == HttpStatusCode.Unauthorized) 


{ 
res.Headers.WwwAuthenticate. Add( 
new AuthenticationHeaderValue("Basic", _realm)); 


} 


return res; 


}); 


return Task.FromResult<object>(null); 
} 


ASP.NET Web API 2.0 还 提供 一 个 名 为 HostAuthenticationFilter 的 Authentication 
Filter 具体 实现 ， 通 过 Katana 身份 认证 管理 器 ， 使 用 Katana 的 身份 验证 中 间 件 。 


HostAuthenticationFilter 的 AuthenticateAsync 方法 一 开始 就 尝试 从 请 求 上 下 文中 获得 
Katana 身份 验证 管理 器 ， 如 果 存 在 身份 验证 管理 器 ， 筛 选 器 就 会 使 用 这 个 管理 器 ， 传 人 已 
配置 的 认证 类 型 ， 进 行 请 求 的 身份 验证 。 身 份 验证 管理 器 在 内 部 检查 已 注册 的 中 间 件 ， 如 
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果 有 兼容 的 中 间 件 ， 那 么 管理 器 会 调用 这 个 中 间 件 ， 对 请 求 进行 身份 验证 (被 动 模式 )， 
或 者 返回 中 间 件 管道 之 前 已 经 执行 的 身份 验证 结果 (主动 模式 )。 














BEI, HostAuthenticationFilter.ChallengeAsync 也 会 尝试 获得 Katana 身份 验证 管理 
器 ， 用 这 个 管理 器 添加 质询 信息 ，Katana 身份 验证 中 间 件 随后 会 使 用 这 些 质询 信息 ， 给 响 
应 添加 WWW-Authenticate 标 头 。 


15.3.11 基于 令 牌 的 身份 验证 
遗憾 的 是 ， 我 们 之 前 介绍 的 基于 密码 的 HTTP 基础 身份 验证 方法 具有 若干 问题 。 首 先 ， 每 
个 请 求 都 必须 发 送 密码 ， 导 致 了 如 下 问题 。 





。 客户 端 必 须 保存 密码 ， 或 者 每 次 请 求 时 从 用 户 获 得 密码 (这 种 做 法 不 太 现 实 )。 还 要 注 
意 的 是 , 密码 必须 以 明文 保存 , 或 者 使 用 一 种 可 逆 的 保护 方式 , 增加 了 密码 泄露 的 危险 。 

。 同样 的 ， 服 务 器 必须 对 每 个 请 求 都 进行 密码 验证 ， 会 增加 很 多 的 开销 。 

。 验证 信息 通常 保存 在 外 部 系统 中 。 

。 为 防御 字典 攻击 而 使 用 的 技术 ， 导 致 验证 过 程 的 计算 开销 高 郧 。 

。 增加 了 信息 偶然 泄露 给 未 授权 方 的 可 能 性 。 





通常 情况 下 ， 密 码 还 具有 很 低 的 不 确定 性 ， 很 容易 受到 字典 攻击 。 这 意味 着 ， 任 何 使 用 密 
码 验 证 的 公共 系统 都 必须 采取 防御 字典 攻击 的 手段 。 例 如 ， 限 制 一 段 时 间 内 允许 发 生 的 错 
误 验 证 次 数 。 


密码 的 应 用 范围 通常 也 很 广 ， 也 就 是 说 ， 客 户 端 访问 某 个 系统 上 任何 资源 ， 使 用 的 都 是 同 
一 个 密码 。 大 部 分 时 候 ， 我 们 应 该 设置 一 个 只 能 访问 一 个 资源 或 某 些 HTTP 方法 的 用 户 
身份 。 

而 且 ， 基 于 密码 的 机 制 不 适合 分 布 式 应 用 。 在 分 布 式 场景 中 ， 身 份 验证 过 程 委 托 给 外 部 系 
统 ， 例 如 : 组 织 的 或 社会 的 用 户 凭证 提供 方 。 最 后 ， 基 于 密码 的 身份 验证 不 能 支持 委托 场 
景 ， 第 16 章 将 对 此 进行 介绍 。 








进行 Web API 身份 验证 的 一 个 更 好 的 方法 是 使 用 安全 令 牌 (security token), RFC 4949 将 

安全 令 牌 定义 为 “用 于 在 身份 验证 过 程 中 验证 用 户 标识 的 〈…… ) 数据 对 象 ”。 典 型 的 

Web 应 用 程序 中 使 用 身份 验证 cookie， 就 是 一 种 基于 令 牌 的 身份 验证 过 程 : 

(1) 使 用 基于 密码 的 认证 机 制 ， 执 行 初始 身份 验证 ， 生 成 一 个 cookie， 返 回 给 客户 端 ; 

(2) 客户 端 之 后 发 出 的 每 个 请 求 ， 都 通过 这 个 cookie 进行 身份 验证 ， 不 再 需要 初始 的 身份 
信息 。 

安全 令 牌 是 一 个 相当 通用 和 抽象 的 概念 。 安 全 令 牌 可 能 以 不 同 的 方式 进行 初始 化 ， 有 具有 不 

同 的 特征 。 接 下 来 ， 我 们 将 介绍 一 些 最 常见 的 设计 变化 。 
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首先 ， 安 全 令 牌 可 以 包含 表示 的 安全 信息 ， 或 者 只 是 对 安全 信息 的 一 个 引用 。 在 二 种 情况 
中 ， 令 牌 只 是 包含 一 个 无 法 伪造 的 引用 ， 指 向 一 个 安全 存储 条 目 ， 这 个 安全 存储 通常 由 令 
牌 颁 发 者 负责 管理 。 这 种 基于 引用 的 令 牌 也 称 为 生成 物 (artifacts)， 基 于 引用 的 令 牌 具有 
两 个 优点 : 


。 长 度 更 短 。 如 果 需 要 在 UR 中 嵌入 令 牌 ， 这 一 点 非常 重要 ， 
。 更 易 撤销 或 取消 。 令 牌 颁发 者 只 需 删 除 这 个 令 牌 指向 的 存储 条 目 即 可 。 


但 是 ， 基 于 引用 的 令 牌 不 是 自 包含 的 (self-contained) : 如 果 要 获取 令 牌 所 代表 的 安全 信 
息 ， 你 通常 需要 对 令 牌 颁发 者 或 者 外 部 存储 进行 查询 。 因 此 ， 当 令 牌 颁发 者 和 使 用 者 是 同 
一 实体 ， 或 者 令 牌 有 长 度 限制 时 ， 人 们 才 会 更 多 使 用 基于 引用 的 令 牌 。 

















令 牌 颁发 者 可 以 生成 足够 长 度 〈 例 如 : 256 位 ) 的 随机 位 串 ， 用 做 无 法 伪造 的 引用 令 牌 。 
然后 令 牌 颁发 者 可 以 用 这 个 引用 的 散 列 值 作为 键 值 ， 存 储 相关 的 安全 信息 。 令 牌 颁发 者 使 
用 了 密码 学 的 散 列 函数 ， 因 此 : 


。 根据 令 牌 内 容 ， 很 容易 计算 出 存储 的 键 值 ， 访 问安 全 信息 ; 

。 根据 存储 的 键 值 ， 很 难 计算 出 有 效 的 令 牌 ， 因 此 如 果 攻 击 者 能 够 读 取 令 牌 存储 内 容 ， 这 
可 以 提供 一 层 额外 的 防御 。 

除了 包含 基于 引用 的 令 牌 ， 令 牌 也 可 以 包含 安全 信息 ， 这 些 信息 安全 地 进行 打包 ， 用 于 两 

个 或 更 多 方 之 间 的 通信 。 这 些 信息 的 打包 需要 使 用 密码 机 制 ， 确 保 令 牌 具有 如 下 特性 。 

















。 保密 性 (confidentiality) 
只 有 通过 身份 验证 的 接受 者 才能 够 访问 所 包含 的 信息 。 


。 完整 性 (integrity) 


接收 方 应 该 能 够 检测 令 牌 在 两 方 之 间 传 输 时 是 否 遭 到 修改 。 


这 种 令 牌 通常 称 为 断言 (assertion)， 具 有 自 包含 的 优点 : 令 牌 使 用 者 无 需 访问 外 部 系统 或 
存储 ， 即 可 获得 安全 信息 。 这 种 令 牌 的 缺点 是 比较 长 ， 可 能 会 超出 实际 URI 的 限制 ， 而 且 
这 种 令 牌 的 产生 和 使 用 需要 使 用 密码 机 制 。SAML (Security Assertion Markup Language， 
安全 断言 标记 语言 ) 断言 就 是 一 种 广泛 使 用 的 自 包含 令 牌 ， 使 用 XML 习 语 表示 安全 
信息 ， 通 过 XML 签名 和 XML 加 密 进行 保护 。 这 种 安全 令 牌 通常 用 于 经 典 的 联邦 协议 
(federation protocol), ， 例 如 : SAML 协议 、WS-Federation 或 WS-Trust。 


JWT (JSON Web Token) 是 一 种 较 新 的 自 包含 令 牌 格式 ， 这 种 格式 基于 ISON 语法 ， 目 的 
是 用 于 “空间 受 限 的 环境 ， 例 如 HTTP 身份 验证 标 头 和 URI 查询 参数 ”。 





下 面 是 一 个 经 过 签名 的 JWT 令 牌 的 示例 : 
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ey JOeXALOLIKV1IQiLCIhbGcLOLIIUZIANiI9. eyJpc3MiOiJodHRwO0i8vaXxNzdWVyLndlYmFwaWJvb 
2submVOTiwiYXVkI joiaHROcDovL2V4YW1wbGUubmVOLiwibmImI joxMzc2NTcxNzAxLCJLeHALOjE 
ZNzY1NzIwMDEsInN1Yi16ImFsaWNLQHd LYmFwaWJvb2submVOIiwiZWihaWwi0iJhbGLljZUB3ZWJhc 
GLib29rLm5LdCIsImShbWUi0iJBbGLIjZSI9. FCO6LOk_hey4O0kqEVuvMfiM8LeXItsYLFNWBOvwbU- I 


IWT 令 牌 有 一 列 组 成 部 分 ， 各 部 分 以 .字符 分 隔 。 每 个 组 成 部 分 是 一 个 base64url 编码 的 八 
位 字 节 流 ， 前 两 个 八 位 字 节 流 是 UTF-8 编码 的 两 个 JSON 对 象 ， 最 后 一 个 是 签名 方案 的 输 
出 。 第 一 个 对 象 (在 令 牌 第 一 部 分 编码 ) 是 JWT 标 头 : 





{"typ" : "JWT" ， "alg" : "HS256"} 





这 个 对 象 定 义 了 令 牌 类 型 ， 以 及 所 用 的 密码 保护 。 在 上 面 这 个 例子 中 ， 令 牌 唯一 的 完整 性 
保护 是 通过 MAC 方案 (HS256 代表 HAMC-SHA256) 添加 的 。 但 是 ，JWT 标 头 也 支持 对 
令 牌 内 容 的 加 密 。 














JWT 令 牌 的 第 二 部 分 是 JWT 声明 集合 (为 便于 阅读 ， 示 例 中 加 入 了 换行 符 ) : 
{ 


"iss":"http://issuer.webapibook.net", 
"aud":"http://example.net", 
"nbf":1376571701, 

"exp":1376572001, 

"sub": "alice@webapibook.net", 
"email": "alice@webapibook.net", 
"name": "Alice" 


} 


JWT 声明 集合 对 象 包含 对 主体 (subject) 的 声明 ， 这 些 声明 由 一 个 颁发 者 (issuer) 进行 断 
言 ， 供 观众 (audience) 使 用 。 这 个 对 象 的 每 个 属性 都 对 应 一 个 声明 类 型 ， 属 性 值 包 含 对 
应 的 声明 值 ， 这 个 值 可 以 是 任何 JSON 值 〈 例 如 : 字符 串 或 数组 )。JWT 规范 定义 了 一 些 
声明 类 型 



































e iss (issure) 标识 令 牌 颁发 者 ; 
e sub (subject) 是 令 牌 主 体 的 唯一 标识 符 ， 令 牌 主 体 即 令 牌 声 明 应 用 的 实体 ; 
。 aud ( 

( 


audience) 标识 声明 所 允许 的 使 用 者 ，; 
e exp (expiration) 和 nbf (not before) 定义 一 个 有 效 时 间 段 。 


示例 15-11 展示 了 如 何 使 用 NuGet 软 件 包 System.IdentityModeL.Tokens.Jwt 中 的 Jwt 
SecurityTokenHandler 类 ， 创 建 和 使 用 一 个 JWT 今 牌 。 


示例 15-11: 创建 和 使 用 JWT 令 牌 


[Fact] 

public void Can_create_and_consume_jwt_tokens() 

{ 
const string issuer = "http://issuer.webapibook.net"; 
const string audience = "the.client@apps.example.net"; 





const int lifetimeInMinutes = 5; 

var tokenHandler = new JwtSecurityTokenHandler(); 

var symmetrickKey = GetRandomBytes(256 / 8); 

var signingCredentials = new SigningCredentials( 
new InMemorySymmetricSecurityKey(symmetricKey) , 
"http: //www.w3.org/2001/04/xmldsig-more#hmac-sha256", 
"http: //www.w3.org/2001/04/xmlenc#sha256"); 


var now = DateTime.UtcNow; 


var claims = new[ ] 


{ 
new Claim("sub", "alice@webapibook.net"), 
new Claim("email", "“alice@webapibook.net"), 
new Claim("name", "Alice"), 

J; 


var token = new JwtSecurityToken(issuer, audience, claims, 


new Lifetime(now, now.AddMinutes(lifetimeInMinutes)), signingCredentials); 


var tokenString = tokenHandler.WriteToken( token) ; 


var parts = tokenString.Split('.'); 
Assert.Equal(3, parts.Length); 


var validationParameters = new TokenValidationParameters() 


{ 
AllowedAudience = audience, 
SigningToken = new BinarySecretSecurityToken(symmetricKey), 
ValidIssuer = issuer, 

J; 


tokenHandler .NameClaimType = ClaimTypes.NameIdentifier; 


var principal = tokenHandler .ValidateToken(tokenString, validationParameters); 


var identity = principal.Identities.First(); 


Assert.Equal("alice@webapibook.net", identity.Name); 


Assert.Equal("alice@webapibook.net", 


identity.Claims.First(c => c.Type == ClaimTypes.NameIdentifier).Value); 


Assert.Equal("alice@webapibook.net", 


identity.Claims.First(c => c.Type == ClaimTypes.Email).Value); 


Assert.Equal("Alice", identity.Claims.First(c => c.Type == 
Assert.Equal(issuer, identity.Claims.First().Issuer); 


} 
(ESS ETT, TokenValidationParameters aL TN eee 例如 ; 





"name").Value); 


允许 的 目的 地 ( 观 


众 ) 和 颁发 者 。 这 些 参数 也 定义 了 签名 验证 密 钥 。 这 个 示例 使 用 了 对 称 签名 方案 ， 因 此 令 
牌 生成 方 和 使 用 方 必须 使 用 同样 的 密 钥 。 如 果 验 证 通过 ， 验 证 方 还 会 产生 一 个 包含 令 牌 声 


明 的 用 户 对 象 。 
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区 分 令 牌 的 另 一 个 特征 是 其 绑 定 到 信息 的 方式 ， 最 常见 的 两 种 方式 是 持 有 者 (bearer) 和 
密 钥 所 有 者 (holder-of-key)。 


RFC 6750 对 持 有 者 令 牌 的 定义 如 下 : 


一 种 安全 令 牌 ， 持 有 这 种 令 牌 的 任何 一 方 〈 一 个 “ 持 有 者 ") 具有 同等 的 使 用 权 。 
使 用 持 有 者 令 牌 不 要 求 持 有 者 证 明 其 拥有 密 钥 (所 有 权证 明 ) 。 


令 牌 和 消息 之 间 无 需 额外 的 绑 定 ， 持 有 者 令 牌 即 可 加 入 一 个 消息 中 。 这 意味 着 能 够 访问 这 
个 纯 文本 信息 的 任何 一 方 都 可 以 获得 其 中 包含 令 牌 ， 无需 任何 额外 知识 便 可 将 其 用 于 男 一 
个 消息 。 在 这 方面 ， 持 有 者 令 牌 与 不 记名 支票 (bearer check) 很 相似 ， 二 者 的 使 用 都 不 需 
要 对 使 用 者 进行 任何 附加 的 身份 证 明 。 


持 有 者 令 牌 很 容易 使 用 ， 但 是 ， 其 安全 性 完全 依赖 以 下 条 件 : 

。 包含 令 牌 的 消息 的 保密 性 ; 

。 确保 令 牌 不 会 发 送 给 错误 的 接收 者 。 

令 牌 的 另 一 种 绑 定 方式 是 使 用 密 钥 持 有 者 (holder-of-key) 方法 。 使 用 这 种 方法 ， 对 每 个 

通过 身份 验证 的 消息 ， 客 户 端 都 必须 提供 绑 定 到 令 牌 的 密 钥 信息 。 客 户 端 通常 的 实现 方法 

是 ， 选 择 消息 的 一 部 分 内 容 ， 使 用 密 钥 计 算出 一 个 对 称 签名 (消息 认证 码 )， 加 入 消息 中 。 

和 使 用 基础 认证 方案 一 样 ， 使 用 持 有 者 令 牌 的 客户 端 和 服务 器 也 共享 一 个 秘密 。 但 是 ， 这 

个 秘密 实际 上 是 用 于 对 消息 进行 签名 和 验证 的 一 个 密 钥 ， 这 个 密 钥 并 不 发 送 。 

。 客户 端 使 用 共享 密 钥 ， 对 请 求 消息 中 精心 选择 部 分 进行 签名 ， 并 将 这 个 签名 附加 到 消息 
上 ， 然 后 将 消息 和 令 牌 (类似 用 户 名 ) 一 起 发 送 至 服务 器 。 

。 服务 器 使 用 这 个 令 牌 获取 客户 端的 共享 秘密 ， 用 于 验证 消息 签名 。 






































这 种 方案 基于 一 个 假设 ， 即 : 对 于 一 个 密码 签名 机 制 ， 只 有 知道 共享 密 钥 的 一 方 能 够 生成 
有 效 的 签名 。 因 此 ， 客 户 端 不 需要 提供 这 个 密 钥 ， 就 能 证 明 自 己 拥有 密 铀 。 

如 果 一 个 恶意 的 第 三 方 捕获 了 请 求 消息 ， 那 么 只 能 得 到 消息 签名 的 值 ， 而 无 法 获得 共享 密 
钥 ， 因 此 无 法 给 新 消息 提供 身份 验证 信息 。 但 是 ， 第 三 方 捕获 的 这 个 消息 签名 是 有 效 的 ， 
因此 可 以 将 其 进行 转发 。 为 了 对 此 进行 防御 ， 你 可 以 组 合 使 用 时 间 惟 和 Nonces。 








时 间 蕉 是 一 个 时 间 值 ， 表 明 源 消 息 产 生 的 时 间 。 时 间 玲 可 以 添加 到 待 发 送 的 信息 ， 也 受到 
签名 的 保护 。 在 服务 器 端 ， 只 有 当 消 息 的 时 间 惟 位 于 接受 窗口 内 (例如: 当前 时 间 加 上 或 
减 去 5 分 钟 ) 时， 服务 器 才 接受 这 个 消息 。 服 务 器 使 用 这 个 时 间 窗 口 ， 以 允许 消息 传送 的 
延迟 和 时 钟 误差 。 
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Nonce (“number used only once” 的 缩写 ) 通常 是 一 个 只 使 用 一 次 的 随机 数 。Nonce 与 时 
ek EA, PTE ENR oe Se a AEA BR, ARS RET A A EK 
Nonce， 如 果 一 个 消息 的 Nonce 已 经 存在 就 会 遭 到 拒绝 。Nonce 与 时 间 戳 一 起 使 用 时 ， 只 
需要 保存 接受 窗口 的 时 间 长 度 即 可 。 








签名 机 制 可 以 分 为 两 种 。 非 对 称 机 制 中 ， 签 名 的 生成 算法 和 验证 算法 使 用 不 同 的 密 钥 一 一 
签名 生成 使 用 私有 密 钥 ， 签 名 验证 使 用 公用 密 钥 。 在 对 称 机 制 中 ， 签 名 生成 和 验证 都 使 用 
同样 的 密 钥 。 消 息 认 证 码 通常 使 用 对 称 机 制 。 这 种 对 称 性 意味 着 ， 任 何 能 够 验证 签名 的 一 
方 也 能 生成 签名 ， 这 与 传统 签名 不 同 ， 使 得 我 们 无 法 确定 签名 者 的 身份 。 但 是 ， 对 称 机 制 
具有 很 好 的 性 能 ， 因 此 通常 在 不 需要 非 对 称 机 制 提 供 的 额外 功能 时 使 用 。 如 果 密 钥 持 有 证 
据 是 基于 消息 认证 码 的， 那么 这 些 令 牌 被 称 为 MAC 令 牌 。 对 称 机 制 通常 也 具有 确定 性 ， 
同一 个 消息 使 用 同一 个 密 钥 总 是 会 产生 通常 的 签名 值 。 因 此 ， 我 们 可 以 计算 签名 值 ， 与 接 
收 到 的 消息 的 签名 值 进行 比较 ， 以 此 进行 签名 验证 。 





构建 MAC 算法 的 一 个 党 用 方法 是 REFC 2014 中 定义 的 HMAC (hash-based message 
authentication code， 基 于 散 列 的 消息 认证 码 )。HMAC 内 部 使 用 了 一 个 密码 学 散 列 函数 。 
例如 ，Amazon S3 使 用 了 HMAC 与 SHA-1 函数 的 组 合 ， 称 为 HMAC-SHA1。Windows 
Azure Blob Service 也 使 用 了 HMAC 算法 ， 但 是 使 用 了 更 新 版 本 的 SHA-256 散 列 函数 
(HMAC-SHA256). 





MAC 令 牌 技术 用 在 若干 身份 验证 方案 中 ， 其 中 有 : 





e Amazon Simple Storage Services (S3) (参见 http://s3.amazonaws.com/doc/s3-developer-guide/ 
RESTAuthentication.html) ; 

e Windows Azure Storage Services (参见 http://msdn.microsoft.com/library/azure/dd179428.aspx) ; 

e OAuth 1.0 协议 (参见 http://tools.ietf.org/html/rfc5849) ; 

。 由 Eran Hammer 提出 的 Hawk HTTP 身份 验证 方案 (参见 https:/github.com/hueniverse/hawk ) 。 














这 四 种 方案 都 使 用 生成 物 令 牌 ， 也 就 是 说 令 牌 只 是 唯一 标识 符 ， 服 务 器 用 其 获取 客户 身份 
声明 和 令 牌 密 钥 。 





图 15-10 展示 了 基于 签名 的 身份 验证 过 程 。 发 送 方 从 消息 中 抽取 一 个 消息 代表 〈 稍 后 进行 
定义 )， 使 用 共享 密 钥 对 其 进行 签名 ， 并 将 生成 签名 值 插入 待 发 送 的 请 求 消息 。 接 收 方 抽 
取消 息 代 表 ， 对 其 进行 签名 ， 将 签名 值 进行 比较 ， 从 而 验证 这 个 签名 。 
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请 求 消息 


eer 有 效 /无 效 











15-10: 消息 签名 计算 








HTTP 中 间 件 可 以 修改 请 求 消 息 的 部 分 内 容 (例如 : 去 除 代 理 标 头 )， 因 此 我 们 不 能 对 整个 
消息 进行 签名 ， 而 是 对 消息 代表 进行 签名 。 消 息 代表 (message representative) 是 从 消息 构 

















建 得 到 的 一 个 字符 串 ， 具 有 如 下 特性 : 


不 受 HTTP 中 间 件 对 消息 的 典型 修改 的 影响 ， 
捕获 了 消息 的 所 有 重要 部 分 。 两 个 语义 不 同 的 消息 不 应 该 有 相同 的 消息 代表 。 

















15.3.12 Hawk 身份 验证 方案 
为 了 使 这 些 抽 象 的 概念 具体 化 ， 这 一 节 我 们 要 简要 介绍 Hawk 身份 认证 方案 。 在 Hawk 身 
份 认 证 方案 中 ， 客 户 端 使 用 换行 符 连接 如 下 元 素 组 成 消息 代表 : 





OA 


字符 串 常 量 "hawk.1.header", 

一 个 时 间 惟 字符 串 ， 代 表 从 GMT 时 间 1970 年 1 月 1 日 0 时 0 分 0 秒 到 现在 的 秒 数 ; 
一 个 Nonce; 

请 求 HTTP 方法 ，; 

Taek URI 路 径 和 查询 ; 

请 求 URI 主机 名 〈 不 包括 端口 ) ; 

请 求 URI 端口 ; 

可 选 的 有 效 载荷 散 列 值 或 空 字符 串 ; 

可 选 的 应 用 相关 的 扩展 数据 或 空 字 符 串 。 





消息 代表 在 构建 之 后 ， 使 用 UTF8 编码 转换 成 一 个 字 节 序列 ， 然 后 提供 给 配置 令 牌 密 铀 
的 MAC 方案 。 与 Amazon 和 Azure 身份 验证 方案 不 同 ，Hawk 方案 支持 多 个 MAC 算法 
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(目前 支持 HMAC-SHAI 和 HMAC-SHA256), MAC 方案 的 输出 (一 个 字 节 序列 ) 后 通过 
Base64 编码 算法 ， 转 换 回 字符 串 。 


请 求 消息 的 Authorization 标 头 使 用 Hawk 方案 字符 串 ， 其 后 跟随 一 组 键 / 值 对 。 





。 id 


所 用 的 时 间 发 。 


e nonce 


所 用 的 Nonce。 


e mac 


MAC 输出 的 Base64 编码 字符 串 。 


e hash 
PE) 有 效 载荷 代表 的 散 列 值 。 


e ext 


(可 选 ) 可 选 的 扩展 数据 。 


FE HPT Ta] BK. Nonce 和 扩展 数据 必须 明确 添加 到 消息 的 Authorization 标 头 ， 使 服务 器 可 
以 重新 构建 消息 代表 。 服 务 器 使 用 id 字段 指明 的 密 钥 ， 从 这 个 消息 代表 重新 计算 出 MAC 
输出 ， 然 后 将 其 与 接收 到 的 mac 字段 进行 比较 。 如 果 比 较 的 MAC 值 不 同 ， 那 么 说 明 消 息 
遭 到 算 改 ， 应 该 拒绝 接受 。 然 而 ， 只 比较 MAC 值 是 不 够 的 ， 攻 击 者 可 能 会 转发 过 去 的 有 
效 信 息 。 为 了 防御 这 种 攻击 ， 服 务 器 应 当 采 取 以 下 操作 。 


。 检查 接收 到 的 Nonce， 确 保 其 未 曾 在 以 前 的 消息 中 使 用 过 。 
。 检查 接收 到 的 时 间 惟 ， 确 保 其 位 于 一 个 接受 时 间 窗 口内 。 这 个 时 间 窗 口 的 默认 值 大 约 是 
一 分 钟 。 


服务 器 还 应 当 存储 接收 到 的 Nonce， 这 些 值 应 该 至 少 保存 接受 时 间 窗 口 的 长 度 。 


Hawk 身份 验证 方案 允许 消息 代表 包含 有 效 载 集 代表 的 散 列 值 ， 以 此 对 请 求 消息 的 有 效 载 
和 荷 进行 保护 。 有 效 载荷 代表 是 以 换行 符 连 接 如 下 元 素 : 









































。 字符 串 常 量 "hawk.1.payLoad'" ; 
。 请 求 内 容 类 型 (例如 : appLication/xmL) ， 其 中 不 包含 参数 ; 
。 在 进行 任何 内 容 或 传输 编码 之 前 的 请 求 有 效 载 答 。 


使 用 有 效 载荷 保护 时 ， 有 效 载荷 代表 字符 串 的 散 列 值 也 包含 在 Authorization pR% (hash 
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FR) 中 ， 使 服务 器 可 以 在 计算 有 效 载荷 散 列 值 之 前 验证 消息 代表 。 








要 了 解 Hawk 身份 验证 方案 的 更 多 细节 ， 你 可 以 访问 https://github.com/hueniverse/hawk, 
这 里 既 有 Hawk 的 非 正式 描述 ， 也 有 一 个 基于 Node.JS 的 具体 实现 。 本 书 的 GitHub 存储 也 
包含 一 个 C# 的 Hawk 方案 实现 ， 称 为 HawkNet。 





下 一 章 主 要 介绍 OAuth 2.0 框架 ， 提 供 了 更 多 具体 的 示例 ， 演 示 基 于 令 牌 的 身份 验证 ， 也 
就 是 获取 和 使 用 令 牌 的 协议 。 


15.4 授权 


我 们 已 经 了 解 到 ， 身 份 认证 处 理 的 问题 是 收集 和 验证 关于 主体 的 信息 ， 也 就 是 身份 声明 。 
而 授权 处 理 的 则 是 一 个 附加 问题 ， 即 控制 这 些 主体 (subject) 对 受 保护 资源 (resource) 可 
以 实施 的 操作 (action)。 图 15-11 展示 了 授权 问题 的 核心 概念 : 主体 、 操 作 和 资源 。 
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15-11: 基础 授权 模式 : 主体 、 操 作 和 资源 


主体 、 操 作 和 资源 的 具体 组 成 很 大 程度 上 依赖 具体 的 上 下 文 。 例 如 ，.NET 框架 提供 一 个 
代码 访问 授权 模型 ， 其 中 资源 是 类 方法 ， 操 作对 应 方法 调用 ， 主 体 则 是 与 运行 线程 相关 的 
用 户 身 份 。 而 在 Web API 中 ， 这 些 概念 映射 则 颇 为 直接 : 


























。 受 保护 的 资源 对 应 于 请 求 消 息 要 访问 的 HTTP 资源 ，; 
。 操作 是 HTTP 方法 (例如: GET 或 DELETE)，; 
。 最 后 ， 主 体 对 应 于 执行 HTTP 请 求 的 HTTP 客户 端 。 


人 们 经 常 将 授权 问题 分 为 几 个 部 分 : 策略 、 决 定 和 执行 。 授 权 策 略 (authorization policy) 
是 定义 允许 情况 的 规范 。 下 面 的 声明 就 是 用 自然 语言 表达 的 一 个 授权 策略 的 示例 : 

















。 “匿名 主体 不 能 执行 不 安全 的 HITP 方法 ”; 
。 “问题 只 能 由 创建 者 或 项 目 经 理 关 闭 ”， 
。 “工作 单 的 标题 只 能 由 创建 者 修改 ”。 




















授权 决定 (authorizatino decision) 是 一 个 过 程 ， 衡 量 由 (主体 ， 操 作 ， 资 源 ) 三 元 组 定 
义 的 一 个 访问 是 否 符 合 规定 的 授权 策略 。 最 后 ， 授 权 执 行 (authorization enforcement) 是 
确保 系统 只 执行 得 到 允许 的 访问 的 机 制 。 授 权 执 行 通常 与 拦截 访问 的 运行 时 机 制 (例如: 
Web API 筛选 器 ) 关系 紧密 ， 而 授权 决定 则 依赖 授权 策略 。 图 15-12 展示 了 这 些 概念 及 其 
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图 15-12: 授权 执行 、 授 权 决 定 和 授权 策略 


在 分 布 式 系统 中 ， 授 权 决 定 和 授权 执行 可 能 在 不 同 的 节点 执行 ， 或 在 多 个 层次 上 执行 。 例 
a: 使 用 OAuth 2.0 框架 〈 详 见 下 一 章 ) 时 ， 你 可 以 在 一 个 外 部 授权 服务 器 (authorization 
server) 上 进行 授权 决定 ， 让 资源 服务 器 (resource server) 负责 确保 只 有 得 到 允许 的 访问 
能 够 执行 。 











授权 也 可 以 在 多 个 层次 上 执行 ， 即 靠近 外 部 世界 的 连接 点 (Web API) ， 或 靠近 域 对 象 和 方 
法 。 这 些 层次 经 常 是 互相 补充 的 。 如 果 在 Web API 层 执行 授权 ， 我 们 可 以 尽早 终止 未 授权 
请 求 的 处 理 ， 但 策略 决定 点 可 能 无 法 访问 所 有 需要 的 领域 信息 ， 不 能 做 出 全 面 的 决定 。 另 
一 方面 ， 在 领域 层 执行 授权 可 以 访问 更 丰富 的 信息 ， 但 是 也 意味 着 未 授权 请 求 会 耗费 较 多 
的 计算 资源 。 本 章 关注 的 重点 是 Web API 层 的 授权 。 











15.4.1 授权 执行 

ASP.NET Web APi 提供 多 种 拦截 HTTP 请 求 的 方法 ， 其 中 一 种 是 授权 和 划 选 器 。 授 权 租 
Beas Oe Fae Hla, PLT UE RE at Za, BAAS EERE a a ZA. A FARN 
i, Pep ove ae AT A Fr Bea 4. ASP.NET Web API 提供 一 个 具体 的 授权 筛选 器 
AuthorizeAttribute， 可 以 用 于 标记 控制 器 类 或 操作 。AuthorizeAttribute 类 有 两 个 定义 授 
权 策 略 的 属性 。 


。 User 是 逗号 分 隔 的 用 户 名 列表 。 如 果 User 不 为 空 ， 那 么 只 有 当 用 户 名 在 列表 中 时 ， 才 
允许 访问 。 

。 Roles 是 逗号 分 隔 的 角色 列表 。 如 果 Roles 不 为 空 ， 那 么 只 有 当 用 户 所 属 某 个 角色 在 列 
表 中 时 ， 才 允许 访问 。 












































示例 15-12 展示 了 如 何 使 用 AuthorizeAttribute, 


e ResourceController 类 的 AuthorizeAttribute 标记 ， 要 求 所 有 请 求 都 进行 认证 。GET 请 
求 是 唯一 的 例外 ， 因 为 Get 操作 标记 为 ALLowAnonymous , 




















。 Delete 操作 的 Authorize(Roles = "ProjectManager") 标记 ， 要 求 所 有 的 DELETE 请 求 都 
必须 由 ProjectManager 角色 的 主体 执行 。 


示例 15-12: 使 用 AuthorizeAttribute 


[Authorize] 
public class ResourceController : ApiController 


{ 
[ALLowAnonymous ] 
public HttpResponseMessage Get() 


{ 


return new HttpResponseMessage 


{ 
}; 


Content = new StringContent("resource representation") 


} 


public HttpResponseMessage Post() 


{ 


return new HttpResponseMessage() 


{ 
+3 


Content = new StringContent("result representation") 


} 
[Authorize(Roles = "ProjectManager") ] 
public HttpResponseMessage Delete(string id) 


{ 
} 


return new HttpResponseMessage(HttpStatusCode.NoContent) ; 
} 
可 是 ， 直 接 在 AuthorizeAttribute 中 定义 授权 策略 的 做 法 ， 使 授权 策略 与 资源 控制 器 绑 定 


在 了 一 起 ， 导 致 任何 的 策略 修改 〈 例 如 :“QA 工程 师 也 可 以 删除 工作 单 ") 都 需要 修改 和 
重新 编译 代码 。 














更 为 合理 的 做 法 应 该 是 让 授权 属性 将 授权 决定 委托 给 外 部 组 件 ， 这 个 外 部 组 件 就 可 以 独 
立地 演化 和 部 署 。 一 种 实现 方法 是 使 用 声明 授权 管理 器 (claims authorization manager), . 
NET 4.5 通过 基 类 ClaimsAuthorizationManager (参见 示例 15-13) 提供 声明 授权 管理 器 的 
概念 。 授 权 声 明 管 理 器 的 主要 作用 是 ， 通 过 CheckAccess 方法 执行 授权 决定 。 在 默认 情况 
下 ，CheckAccess 方法 返回 true， 但 是 派生 类 可 以 重 写 这 个 方法 ， 实 现 定制 的 授权 策略 。 























示例 15-13: Æ% ClaimsAuthorizationManager 


public class ClaimsAuthorizationManager : ICustomIdentityConfiguration 


{ 
public virtual bool CheckAccess(AuthorizationContext context) 
{ 
return true; 
} 
} 





CheckAccess 方法 的 参数 是 一 个 AuthorizationContext 类 (参见 示例 15-14)， 这 个 类 通过 
(主体 ， 操 作 ， 资 源 ) 三 元 组 表示 一 个 访问 ， 其 中 资源 由 ClaimsPrincipal 表示 。 有 趣 的 
是 ， 操 作 和 资源 都 由 声明 表示 。 还 要 注意 的 是 ，AuthorizationContext 类 与 授权 执行 机 制 
无 关 ， 也 就 是 说 ，AuthorizationContext 类 独立 于 Web API 或 其 他 类 似 技术 。 














示例 15-14: 描述 访问 的 AuthorizationContext 类 


public class AuthorizationContext 


{ 
public ClaimsPrincipal Principal 
{ 
get {...} 
} 
public Collection<Claim> Action 
{ 
get {...} 
} 
public Collection<Claim> Resource 
{ 
get {...} 
} 
public AuthorizationContext(ClaimsPrincipal principal, 
Collection<Claim> resource, 
Collection<Claim> action) 
{...} 
} 


程序 库 Thinktecture.IdentityModel.45 (https://github.com/thinktecture/Thinktecture.Identity 
Model) 提供 了 一 个 ClaimsAuthorizAttribute， 使 用 策略 为 ， 当 Web API 运行 时 调用 这 个 属 
性 ， 检 查 请 求 是 否 得 到 允许 时 ， 这 个 属性 将 此 决定 委托 给 已 注册 的 单 例 ClaimsAuthorization 
Manager, ClaimsAuthorizAttribute 使 用 一 个 授权 上 下 文 参数 ， 其 中 包含 了 请 求 的 声明 用 
户 对 象 、 操 作 名 和 控制 器 名 。 示 例 15-15 实现 了 一 个 定制 的 授权 管理 器 ， 实 现 示例 15-12 
中 定义 的 授权 策略 。 这 两 个 示例 的 主要 区 别 在 于 ， 示 例 15-15 将 授权 策略 外 部 化 ， 在 一 个 
单独 的 组 件 中 实现 ， 这 个 组 件 可 以 独立 演化 和 编译 。 


























示例 15-15: 一 个 定制 的 ClaimsAuthorizationManager 类 


public class CustomPolicyClaimsAuthorizationManager : ClaimsAuthorizationManager 
{ 
public override bool CheckAccess(AuthorizationContext context) 
{ 
var subject = context.Principal; 
var method = context.Action 
.First(c => c.Type == ClaimsAuthorization.ActionType) .Value; 
var controller = context.Resource 
.First(c => c.Type == ClaimsAuthorization.ResourceType).VaLue; 


if (controller == "ClaimsResource") 





if (method.Equals("GET", StringComparison.OrdinalIgnoreCase)) 
return true; 


if (method.Equals("DELETE", StringComparison.OrdinalIgnoreCase) 
&& !subject.IsInRole("ProjectManager") ) 
return false; 
return subject.Identity.IsAuthenticated; 
return false; 


} 


下 一 章 将 接着 讨论 授权 ， 介 绍 OAuth 2.0 框架 。 在 那 之 前 ， 我 们 先 来 看 另 一 种 授权 : 控制 
浏览 器 对 跨 域 资源 的 访问 。 


15.4.2 ” 跨 域 资源 共享 


用 户 代 理 ， 如 浏览 器 ， ca ea (例如 : HTML 文档 和 脚本 程序 ) 进 aa 
及 处 理 。 通 常情 况 下 ， 这 些 资 源 有 着 不 同 的 信任 级 别 ， 可 能 包含 一 些 恶 意 站 点 ， 亡 图 破坏 
其 他 站 点 内 容 的 保密 ee 性 。 同 源 策略 eee policy) 是 用 户 代理 执行 Feit 组 
安全 策略 ， 这 种 策略 使 用 内 容 的 源 ， 对 这 些 内 容 可 以 如 何 交互 进行 限制 ， 也 就 是 通过 用 户 
代理 的 内 部 API 进行 授权 〈 例 如 : DOM 访问 和 网 络 ) 。 









































“WR” (origin) 的 概念 (参见 RFC 6454) 将 URI 按照 其 方案 、 主 机 名 和 端口 进行 组 织 。 简 
单 地 说 ， 如 果 两 个 URI 具有 相同 的 (方案 ， 主 机 名 ， 端 口 ) 三 元 组 ， 就 是 同 源 的 。 例 如 : 
http://example.coom/ 和 http://example.com:80/path 具有 相同 的 源 ， 而 http://example.com 和 
http://www.example.com 具有 不 同 的 源 。 


X 








XMLHttpRequestAPI 就 属于 使 用 同 源 策略 的 用 户 代 理 API。 当 一 个 请 求 通过 open 方法 进行 
初始 化 时 ，XMLHttpRequestAPI 对 象 对 以 下 URI 的 源 进行 比较 : 


。 受到 请 求 的 URI; 
。 初始 化 这 个 XMLHttpRequest 的 文档 的 URI. 


只 有 当 这 两 个 URI 上 共有 相同 的 源 时 ， 这 个 请 求 才 得 到 人 允许， 从 而 禁止 了 跨 域 (cross- 
origin) 请 求 。 


因为 基于 cookie 的 身份 信息 会 自动 附加 到 每 个 发 送 的 请 求 ， 因 此 同 源 策略 对 于 浏览 器 上 下 
文 特别 重要 。 例 如 : 如果 一 个 浏览 器 有 访问 https://banking.example.net 的 有 效 的 身份 验证 
cookie， 那 么 这 些 cookie 会 自动 附加 到 任何 发 送 到 这 个 源 的 请 求 。 如 果 一 个 来 自 外 部 源 的 
恶意 脚本 得 到 允许 ， 可 以 执行 对 https://banking.example.net 的 请 求 ， 那 么 该 请 求 会 自动 通 
过 身份 验证 ， 脚 本 就 可 以 访问 https://banking.example.net 上 的 受 保护 资源 。 同 源 策 略 可 以 
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防御 这 种 类 型 的 攻击 。 


但 是 ， 在 有 些 情况 下 ， 资 源 人 允许 对 来 自 其 他 源 内 容 的 访问 进行 授权 ， 跨 域 请 求 限制 也 禁止 
了 这 些 合法 场景 。CORS (Cross-Origin Resource Sharing， 跨 域 资 源 共 享 ) 是 一 个 W3C 的 
工作 草案 ， 定 义 了 一 种 机 制 ， 人 允许 待 访问 资源 对 跨 域 请 求 进行 授权 ， 从 而 允许 跨 域 资源 
访问 。CORS 基于 额外 的 HTTP 请 求 和 响应 标 头 ， 以 及 用 户 代理 的 一 组 处 理 规则 ， 即 支持 
CORS 的 XMLHttpRequest 实现 。 








简单 说 来 ，CORS 规范 规定 ， 跨 域 请 求 必 须 由 XMLHttpRequest 通过 两 种 方式 执行 。 一 种 方 
式 是 使 用 简单 跨 域 请 求 算法 (simple cross-origin request algorithm) ， 预 先 发 送 请 求 ， 但 是 
只 有 当 发 起 调用 的 脚本 明确 得 到 资源 授权 时 ， 才 能 看 见 请 求 结果 ， 男 一 种 方法 是 使 用 带 有 
预 检 算 法 的 跨 域 请 求 (cross-origin request with preflight algorithm)， 预 先 执 行 一 个 OPTIONS 
请 求 〈 即 预 检 ) ， 查 询 资源 是 否 授权 跨 域 访问 。 只 有 当 得 到 肯定 的 查询 结果 时 ， 才 执行 原 
本 的 请 求 。 


简单 算法 是 只 针对 于 跨 域 请 求 的 一 项 优化 ， 即 使 没有 CORS ， 脚 本 也 可 能 已 经 发 起 了 跨 域 
请 求 。 例 如 ， 一 个 脚本 程序 可 以 使 用 动态 生成 并 提交 的 HTML 表单 ， 发 起 跨 域 GET 或 POST 
请 求 。 这 意味 着 ， 资 源 必 须 做 好 准备 ， 正 确 处 理 基于 跨 域 请 求 的 攻击 ， 这 种 攻击 通常 称 为 
CSRF (Cross-Site Request Fogery， 跨 站 请 求 伪 造 ) 攻击 。 在 这 种 情况 下 ， 支 持 CORS 的 
XMLHttpRequest 只 需要 确保 ， 只 有 明确 得 到 资源 授权 时 ， 请 求 的 响应 才 对 脚本 可 见 。 





























在 满足 以 下 条 件 时 ， 跨 域 请求 可 以 使 用 简单 算法 : 


。 请 求 方法 为 GET、HEAD BY POST (所 谓 的 简单 方法 ) ; 
。 由 脚本 明确 添加 的 请 求 标 头 都 是 简单 标 头 (Accept、Accept-Language、Content- 
Language 或 Content-Type) ; 





。 内 容 类 型 为 application/x-www-form-urlencoded, multipart/formdata 或 text/plain, 


假设 我 们 有 一 个 脚本 ， 位 于 从 http://www.example.net 加 载 的 一 个 文档 中 ， 想 要 使 用 
XMLHttpRequest API, 访问 位 于 https://api.example.net 的 一 个 资源 (主机 名 和 方案 不 同 ， 因 
此 脚本 和 资源 的 源 不 同 )。 如 果 满 足 简 单 算法 的 所 有 限制 条 件 ， 支 持 CORS 的 用 户 代 理 就 
会 预先 发 送 这 个 请 求 ， 在 请 求 中 加 入 一 个 Origin 标 头 ， 标 头 值 为 文档 的 源 (http://www. 


example.net) : 




















GET https://api.example.net/api/resource HTTP/1.1 
Host: api.example.net 

Origin: http: //www.example.net 

Referer: http://www.example.net/ 

















这 时 由 资源 负责 判断 ， 源 http://www.example.net 是 否 有 权 访 问 资源 。 如 果 有 权 访 问 ， 那 么 
返回 的 响应 必须 包含 一 个 Access-ControL-ALLow-0rigin， 表 示 赋 予 这 个 源 访 问 权 限 : 





HTTP/1.1 200 OK 

Content-Length: 23 

Content-Type: text/plain; charset=utf-8 
Access-Control-Allow-Origin: http://www.example.net 


resource representation 


当 用 户 代 理 接收 这 个 响应 ， 并 确认 响应 中 包含 了 对 请 求 者 源 的 Access-Control-Allow- 
Origin 后 ， 就 将 这 个 响应 交 给 发 起 调用 的 脚本 。 如 果 响 应 中 没有 Access-ControL-ALLow- 
Origin 或 者 不 包含 调用 者 的 源 ， 那 么 用 户 代 理 就 会 向 发 起 调用 的 脚本 传 回 一 个 网 络 错误 。 
请 注意 ， 如 果 资 源 不 支持 CORS， 那 么 响应 中 不 会 包含 Access-Control-Allow-Origin,， 用 
户 代 理 回 将 其 解释 为 拒绝 访问 。 


如 果 简 单 算法 的 条 件 中 有 任何 一 个 不 满足 (例如 : 请 求 使 用 PUT Be DELETE 方法)， 那 么 
CORS 规范 使 用 一 个 预 检 请 求 :用户 代理 首先 对 资源 执行 一 个 OPTIONS 请 求 ， 检 查 该 资源 
是 否 支 持 跨 域 请 求 。 这 个 请 求 包含 一 个 值 为 调用 者 的 源 的 Origin 标 头 ， 以 及 值 为 所 请 求 的 
HTTP 方法 的 Access-ControL-Request-Method: 




















T 











OPTIONS https://api.example.net/api/resource HTTP/1.1 
Host: api.example.net 

Access-Control-Request-Method: PUT 

Origin: http://www.example.net 
Access-Control-Request-Headers: origin 

Referer: http://www.example.net/ 


支持 CORS 的 资源 会 使 用 这 个 源 以 及 方法 信息 ， 判 断 是 否 人 允许 跨 域 访问 。 如 果 人 允许 访问 ， 
该 资源 会 生成 一 个 包含 Access-ControL-ALLow-0rigin 和 Access-ControL-ALLow-Methods 标 
头 的 响应 消息 。 


HTTP/1.1 200 OK 

Access-Control-Allow-Origin: http://www.example.net 
Access-Control-Allow-Methods: PUT 

Content-Length: 0 


只 有 接收 到 这 个 表明 允许 访问 的 响应 后 ， 用 户 代 理 才 会 执行 原本 的 请 求 。 


PUT https://api.example.net/api/resource HTTP/1.1 
Host: api.example.net 

Connection: keep-alive 

Origin: http://www.example.net 

Referer: http://www.example.net/ 


同样 ， 只 有 当 响应 中 包含 值 为 脚本 源 的 Access-Control-Allow-Origin 标 头 时 ， 用 户 代理 才 
会 将 啊 应 消息 交 给 发 起 调用 的 脚本 。 








HTTP/1.1 204 No Content 
Access-Control-Allow-Origin: http://www.example.net 








为 了 进行 优化 ， 资 源 也 可 以 在 预 检 响 应 中 包含 一 个 Access-Control-Max-Age， 人 允许 用 户 代 
理 在 该 标 头 定义 的 时 间 内 ， 将 这 个 响应 保存 在 一 个 预 检 结果 缓存 (preflight result cache) 
中 。 这 个 功能 可 以 减少 需要 执行 的 预 检 请 求 数量 。 





15.4.3 ASP.NET Web API 的 CORS 支 持 


ASP.NET Web API 2.0 增加 了 对 CORS 规范 的 支持 ， 提 供 定义 跨 域 策略 和 执行 机 制 的 方法 。 
你 可 以 调用 HttpConfiguration 对 象 的 Enablecors 扩展 方法 ， 激 活 全 局 的 跨 域 支持 。 





config.EnableCors(); 

然后 ， 你 可 以 使 用 EnableCorsAttribute， 明 确 标 记 应 该 支持 CORS 的 控制 器 或 操作 。 
[EnableCors(...)] 
public class ResourceController : ApiController 


{ 
} 


你 也 可 以 向 Enablecors 方法 传人 一 个 EnableCorsAttribute 实例 ， 定 义 全 局 的 跨 域 支持 。 
config.EnableCors(new EnableCorsAttribute(...)); 


EnableCorsAttribute 不 仅 激活 了 跨 域 支持 ， 而 且 定 义 了 人 许 的 跨 域 策 略 〈 例 如 : 允许 的 源 
或 者 请 求 方法 集合 )。 为 此 ，EnableCorsAttribute 的 构造 函数 参数 有 : 允许 的 源 、 允 许 的 
请 求 方法 ， 以 及 允许 和 提供 的 标 头 。EnabLeCorsAttribute 还 可 以 定义 预 检 过 期 时 间 。 
[EnableCors(origins:"https://localhost", headers:"*", methods:"GET", 
PreflightMaxAge = 60)] 


public class ResourceController : ApiController 


{ 

} 
正如 我 们 预期 的 ， 由 标记 操作 的 属性 定义 的 策略 ， 优 先 级 高 于 标记 控制 器 类 的 属性 定义 的 
策略 。 传 给 config.EnableCors 的 属性 定义 的 是 默认 策略 ， 当 请 求 的 控制 器 和 操作 都 没有 
相关 策略 时 ， 系 统 就 会 使 用 默认 策略 。 


除了 这 个 简单 属性 模型 ，Web API 内 部 还 提供 一 个 可 扩展 基础 结构 (参见 图 15-13)， 可 以 
用 别 的 方式 定义 跨 域 策略 。 





跨 域 策略 由 CorsMessageHandler 执行 。CorsMessageHandler 由 EnableCors 方法 插入 请 求 管 
道中 ， 当 一 个 HTTP 请 求 到 达 时 ， 这 个 处 理 程序 检查 Origin 标 头 ， 验 证 是 否 支 持 CORS, 
如 果 支 持 CORS， 那 么 这 个 处 理 程序 会 构建 一 个 CorsRequestContext， 其 中 包含 CORS 相 
关 的 请 求 信息 。 


























public class CorsRequestContext 
{ 
public Uri RequestUri { get; set; } 
public string HttpMethod { get; set; } 
public string Origin { get; set; } 
public string Host { get; set; } 
public string AccessControlRequestMethod { get; set; } 
public bool IsPreflight {get;} 
LE aks 





15-13; CORS 运行 时 







HttpResponseMessage 
















随后 ， 这 个 处 理 程序 使 用 配置 中 注册 的 ICorsPolicyProviderFactory， 尝 试 找到 该 请 求 的 
策略 提供 程序 。 


public interface ICorsPolicyProviderFactory 


{ 
ICorsPolicyProvider GetCorsPolicyProvider(HttpRequestMessage request); 
} 
public interface ICorsPolicyProvider 
{ 
Task<CorsPolicy> GetCorsPolicyAsync(HttpRequestMessage request, 
CancelLationToken cancellationToken) ; 
} 


两 个 接口 是 必须 的 ， 因 为 工厂 类 是 静态 定义 的 ， 而 每 个 请 求 的 策略 提供 程序 可 能 不 同 。 





总 
跨 域 策略 是 下 面 的 类 的 一 个 实例 : 


public class CorsPolicy 
{ 
public bool AllowAnyHeader { get; set; } 
public bool AllowAnyMethod { get; set; } 
public bool AllowAnyOrigin { get; set; } 
public IList<string> ExposedHeaders { get; private set; } 
public IList<string> Headers { get; private set; } 








public IList<string> Methods { get; private set; } 
public IList<string> Origins { get; private set; } 
public long? PreflightMaxAge { get; set; } 
public bool SupportsCredentials { get; set; } 

} 


CorsMessageHandler 使 用 这 个 CorsPolicy 实例 ， 将 请 求 的 CorsRequestContext 转换 为 一 
个 CorsResult， 然 后 应 用 于 HTTP 响应 。 因 此 ， 你 可 以 定义 一 个 新 的 ICorsPolicyProvider 
Factory， 在 配置 中 进行 注册 (扩展 方法 SetCorsPolicyProviderFactory 可 以 完成 这 项 任 
务 )， 完 全 改变 CORS 策略 的 定义 方式 。 





默认 情况 下 ，AttributeBasedPoLicyProviderFactory 类 实现 ICorsPolicyProviderFactory 
接口 ， 检 查 控制 器 和 操作 描述 符 是 否 带 有 EnableCorsAttribute 属性 。 有 具体 实现 根据 CORS 
请 求 类 型 而 不 同 。 对 于 非 预 检 请 求 ，CorsMessageHandler 处 理 程序 首先 将 请 求 转发 到 其 
内 部 处 理 程序 。 当 响应 返回 时 ， 处 理 程序 使 用 选中 的 操作 描述 符 ( 保 存在 请 求 属性 中 )， 
判断 是 否 有 与 操作 或 控制 器 关联 的 EnableCorsAttribute。 如 果 有 ， 处 理 程序 使 用 这 个 
EnableCorsAttribute 获得 策略 EnableCorsAttribute 实现 了 ICorsPolicyProvider 
并 将 生成 的 CorsResult 应 用 于 返回 的 响应 。 这 一 操作 给 返回 的 响应 消息 添加 了 附带 的 
CORS 标 头 。 


但 是 ， 对 于 预 检 请 求 ， 操 作 略 有 不 同 。 请 记 住 ， 预 检 请 求 使 用 OptionsHTTP 方法 ， 用 于 
探测 服务 器 似乎 否 对 给 定 的 请 求 URI 和 方法 对 (方法 在 Access-Control-Request-Method 
标 头 中 ) 提供 CORS 支持 。 也 就 是 说 ， 处 理 预 检 请 求 时 服务 器 不 应 该 执行 任何 操作 。 因 
些 ， 当 服务 器 收 到 一 个 预 检 请 求 时 ，CorsMessageHandler 会 将 OPTIONS 方法 替换 为 Access- 
Control-Request-Method 中 指定 的 方法 ， 然 后 使 用 Web API 解析 服务 ， 找 到 映射 到 该 请 求 
的 控制 器 和 操作 。 但 是 ， 这 个 控制 和 操作 不 会 得 到 调用 ， 而 只 是 用 于 找到 和 获取 CORS R 
I (由 `EnableCorsAttribute 提供 )。 最 后 ， 处 理 程序 创建 和 返回 预 检 响 应 ， 提 前 结束 任何 
上 层 栈 中 的 处 理 。 简 言 之 ， 这 些 预 检 请 求 永远 不 会 到 达 控 制 器 层 。 


























































































































15.5 “小 结 


本 章 介绍 了 在 设计 、 实 现 和 使 用 Web API 时 必须 解决 的 一 些 安全 问题 。 我 们 主要 关注 了 与 
Web API 相关 的 安全 概念 和 技术 : 传输 安全 、 身 份 认 证 和 授权 。 下 一 章 将 继续 进行 安全 主 
题 ， 介 绍 OAuth 2.0 框架 。 但 是 ， 虽 然 其 他 一 些 安全 主题 没有 包括 在 这 本 书 中 ， 我 们 也 不 
应 该 将 其 忽略 。 与 Web 应 用 程序 类 似 ， 在 大 部 分 时 候 ，Web API 是 外 部 因特网 与 关键 业务 
内 部 系统 之 间 的 连接 点 。 因 此 ， 安 全 编码 实践 ， 例 如 : 输入 验证 、 适 当 的 输出 编码 和 各 种 
注入 攻击 的 防御 (AN SQL 注入 ) ， 仍 然 是 至 关 重 要 的 。 
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0Auth 2.0 授 权 框 架 


被 授予 的 权力 不 能 再 次 被 授 出 。 


RFC 6749 定义 的 OAuth 2.0 授权 框架 ， 是 OAuth 1.0 协议 的 演化 版 本 。 在 这 本 书 编写 时 ， 
已 经 有 多 个 流行 的 Web API 使 用 了 OAuth 2.0 授权 框架 ,例如 : Google API, Facebook 和 
GitHub, OAuth 2.0 授权 框架 主要 应 用 于 委托 的 受 限 授权 。 请 看 图 16-1 中 的 虚构 场景 。 















存储 
私有 代码 





构建 和 
分 析 代码 


checkcode.example 
获取 Alice 的 代码 











图 16-1: 委托 授权 场景 
在 这 张 图 中 ， 你 可 以 看 到 : 
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。 storecode.example 是 一 个 存储 和 管理 代码 的 网 站 ， 并 提供 相关 的 Web API; 

。 checkcode.example 是 一 个 构建 和 分 析 代 码 的 服务 ， 并 提供 一 些 功能 ， 例 如 持续 集成 、 编 
码 规则 检查 、 错 误 估计 以 及 测试 覆盖 ，; 

。 Alice 使 用 storedcode.example 网 站 ， 存 储 和 管理 自己 的 私有 代码 。 








Alice 希望 使 用 checkcode.example 服务 ， 分 析 自 己 存 储 在 storedcode.example 的 代码 。 
storedcode.example 提供 一 个 API， 使 得 这 个 使 用 场景 成 为 可 能 ， 但 是 还 存在 一 个 问题 : 
Alice 怎样 允许 checkcode.example 访问 她 的 一 些 私 有 代码 存储 ? 








要 解决 这 个 问题 ，Alice 可 以 向 checkcode.example 提供 自己 访问 storecode.example 所 使 用 
的 身份 信息 (例如: 用 户 名 和 密码 ) checkcode.example 就 可 以 访问 Alice 的 私有 代码 。 但 
是 ， 这 种 做 法 存在 如 下 几 个 缺点 。 


。 持 有 这 些 身 份 信息 ，checkcode.example 可 以 执行 任何 Alice 有 权 进 行 的 操作 ， 包 括 访问 
Alice 的 所 有 代码 ， 还 可 以 进行 修改 。 换 句 话 说， 这 种 做 法 赋予 了 checkcode.example 对 
storecode.example 不 受 限 的 权限 (unconstrained authorization ) 。 

e 如 果 checkcode.example 受到 攻击 ， 可 能 会 泄露 Alice 的 密码 ， 攻 击 者 就 可 以 对 Alice 的 
资源 拥有 完全 控制 。 

。 如 果 Alice 要 撤销 checkcode.example 的 权限 ， 只 能 修改 自己 的 身份 信息 。 而 这 么 做 ， 其 
他 有 权 访 问 Alice 代码 的 应 用 程序 〈 例 如 : 提供 托管 服务 的 www.hostcode.example) 的 
权限 也 会 撤销 。 





一 个 更 好 的 解决 办 法 是 ，Alice 向 checkcode.example 赋予 一 个 受 限 授权 (constrained 
authorization) ， 只 人 允许 checkcode.example 在 一 个 限定 的 时 间 段 内 执行 一 部 分 操作 〈 例 如 ， 
读 取 一 个 代码 库 的 主 分 支 )。Alice 还 应 当 能 够 随时 撤销 这 个 授权 ， 而 不 会 影响 访问 她 的 资 
源 的 其 他 服务 。 














非 虚构 场景 


在 我 们 编写 这 本 书 时 ，AppHarbor PaaS (Platform as a Service, http://support.appharbor.com/ 
kb/3rd-party-integrations/integrating-with-github) 和 Travis CI (http://docs.travis-ci.com/user/ 
getting-started/) 持续 继承 服务 都 使 用 OAuth 2.0 和 委托 授权 ， 与 GitHub 存储 库 进 行 集成 。 











之 前 这 个 示例 说 明了 ， 使 用 简单 客户 端 - 服务 器 模型 表达 Web API 授权 需求 的 不 足 之 处 。 
也 就 是 说 ， 因 为 Web API 是 应 用 程序 使 用 的 接口 ， 所 以 授权 模型 的 一 个 重要 功能 是 ， 区 分 
客户 端 应 用 程序 和 人 类 用 户 。 为 此 ，OAnuth 2.0 框架 引入 了 一 个 具有 四 个 角色 的 模型 。 


。 Alice 扮演 的 角色 是 资源 所 有 者 一 一 拥有 受 保护 资源 ， 或 者 能 够 授予 访问 受 保护 资源 权 
限 的 实体 。 在 本 章 后 面 的 部 分 ， 我 们 将 把 资源 所 有 者 简单 称 作用 户 。 
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。 storecode.example 扮演 的 角色 是 资源 服务 器 一 提供 访问 受 保护 资源 的 接口 的 实体 。 

。 checkcode.example 扮演 角色 的 是 客户 茹 一 一 代表 资源 所 有 者 访问 受 保护 资源 的 应 用 程序 。 

。 授权 服务 器 是 第 四 个 角色 ， 负 责 管理 授权 和 颁发 权限 。 通 常情 况 下 ， 这 个 角色 由 资源 服 
FRE. BÆ, OAuth 2.0 框架 允许 单独 部 署 这 些 角色 。 





这 个 模型 的 一 个 主要 特点 是 ， 在 这 一 场景 中 用 户 和 客户 端 不 同 义 。 用 户 和 客户 端 是 单独 的 
实体 ， 各 自 有 完整 定义 的 身份 ， 大 多 数 时 候 分 属 不 同 的 安全 领域 。 例 如 ， 对 受 保护 资源 的 
访问 经 常 涉 及 与 资源 所 有 者 〈 用 户 ) 和 代表 所 有 者 执行 访问 的 应 用 程序 (客户 端 )。OAuth 
2.0 模型 的 这 一 特点 与 之 前 介绍 的 简单 的 客户 端 -服务 器 场景 完全 不 同 。 但 是 ， 虽 然 重点 
是 委托 授权 和 用 户 - 客户 端 - 服 务 器 模型 ，OAuth 2.0 框架 也 支持 较为 简单 的 场景 ， 即 客 
户 端 自发 进行 资源 访问 ， 没 有 用 户 的 介入 。 











Thinktecture 授权 服务 器 


Thinktecture 授权 服务 器 (参见 https://github.com/thinktecture/Thinktecture.Authorization Server) 
是 一 个 开源 的 OAuth 2.0 授权 服务 器 ， 基 于 .NET 平台 ， 以 C# 编写 。Thinktecture 授权 
服务 器 独立 于 具体 的 资源 服务 器 或 用 户 赁 证 提供 方 ， 适 用 于 更 广泛 的 应 用 场景 。 作 为 
开源 软件 ，Thinktecture 授权 服务 器 是 学 习 OAuth 2.0 设计 和 实现 细节 的 极 佳 学 习 材 料 。 
因此 ， 在 本 章 中 我 们 将 以 Thinktecture 授权 服务 器 为 例 进行 讲解 。 为 简单 起 见 ， 我 们 
将 Thinktecture 授权 服务 器 简称 为 T.AS。 


16.1 客户 端 应 用 程序 


OAuth 2.0 框架 设计 为 支持 不 同类 型 的 客户 端 应 用 程序 ， 例 如 : 














。 经 典 的 服务 器 端 Web 应 用 程序 ， 
。 本 地 应 用 程序 ， 特 别 是 移动 应 用 ， 
。 基于 JavaScript 的 客户 端 Web 应 用 程序 ,如 SPA(Single-Page Application , 单 页 应 用 程序 ) o 


如 此 多 的 客户 端 类 型 带 来 了 不 同 的 挑战 ， 特 别 是 对 于 身份 验证 信息 长 期 存储 的 处 理 。 为 了 
加 入 OAuth 2.0 部 署 ， 一 个 客户 端 必须 预先 在 授权 服务 器 注册 。 在 典型 的 OAuth 2.0 场景 
中 ， 客 户 端 所 有 者 会 提供 一 组 信息 ， 例 如 : 


。 供 人 类 读 取 的 描述 信息 ， 例 如 应 用 程序 名 称 、 商 标 、 主 页 或 版 本 信息 ， 
。 协议 中 用 到 的 技术 信息 ， 例 如 重 定向 URI 或 所 需 的 授权 范围 。 








另 一 方面 ， 授 权 服 务 器 给 客户 端 分 配 一 个 client_id 字符 串 作 为 唯一 标识 。 有 些 客户 端 可 
能 还 会 收 到 一 个 client_secret 字符 串 ， 可 以 在 一 些 协议 步骤 中 在 认证 服务 器 上 进行 身份 
验证 。 在 这 种 情况 下 ，OAuth 2.0 将 客户 端 分 为 如 下 两 类 。 
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。 保密 客户 端 可 以 安全 存储 cLient_secret， 将 其 用 在 协议 步骤 中 。 这 种 客户 端的 典型 例 
子 是 传统 的 服务 器 端 Web 应 用 程序 ， 客 户 端的 凭证 就 存储 在 服务 器 端 。 

。 公共 客户 端 无 法 安全 保存 用 户 凭证 。 这 种 客户 端 没 有 client_secret， 但 是 仍然 有 分 
配 的 client_id。 公 共 客 户 端的 典型 例子 是 客户 端的 JavaScript 应 用 程序 ， 客 户 端的 
JavaScript 应 用 程序 完全 在 用 户 的 浏览 器 中 运行 ， 因 此 不 能 安全 保存 长 期 凭证 。 





根据 客户 端 所 有 者 提供 的 输入 信息 ， 在 注册 时 客户 端 通常 归 类 为 保密 客户 端 和 公共 客 
户 端 。 








在 我 们 编写 这 本 书 时 ， 通 常 是 由 客户 端 所 有 者 通过 Web 表单 进行 客户 端 注 册 ， 表 单 如 图 16-2 
所 示 。 

















Applications / Register a new OAuth application 





Application name 





Something users will recognize and trust A 


Drag & drop 


Homepage URL 


The full URL to your application's homepage 


Authorization callback URI or choose an image 


Your application's callback URL; read our OAuth documentation for more information 
Application description (optional 


This is displayed to all potential users of your application 


Register application 


图 16-2; GitHub 的 客户 端 注册 表单 (2013) 











但 是 ，OAuth IETF 工作 组 (参见 https://datatracker.ietf.org/doc/draft-ietf-oauth-dyn-reg/) 也 
在 制定 一 个 规范 ， 定 义 如 何 使 用 Web API 动态 注册 客户 端 。 





授权 服务 器 也 可 以 将 授权 策略 与 已 注册 客户 端 进行 关联 ， 限 制 客户 端的 权限 。 例 如 ， 在 图 
16-3 的 T.AS 客户 端 模型 中 ， 我 们 可 以 看 到 ， 一 个 客户 端 与 下 列 概念 相关 联 : 


。 客户 端 可 以 参与 的 OAuth 2.0 i; 
。 客户 端 可 以 得 到 委托 的 一 组 授权 一 一 即 范围 ( 稍 后 进行 介绍 )。 
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16-3: T.AS 的 客户 端 类 模型 


16.2 访问 受 保护 资源 


在 OAuth 2.0 框架 中 ， 客 户 端 访问 受 保护 资源 时 ， 必 须 提 供 一 个 访问 令 牌 (access token) 


(参见 图 16-4)。 在 我 们 编写 这 本 








Bit, OAuth 2.0 框架 只 定义 了 持 有 者 令 牌 的 用 法 "， 即 : 





将 访问 令 牌 简单 添加 到 请 求 消 息 中 ， 无 需 进行 更 多 的 绑 定 。 我 们 前 面 介绍 过 ， 持 有 者 令 


牌 的 使 用 较为 简单 ， 但 是 具有 若干 安全 缺点 。 特 别 是， 为 使 用 传输 
保 令 牌 只 发 送 到 关联 的 资源 服务 器 时 ， 不 应 该 使 用 持 有 者 令 牌 。 因 














安全 ， 客 户 端 必 须 确 
为 持 有 者 令 牌 的 这 些 


局 限 ，OAuth IETF 工作 组 也 在 制定 基于 MAC 访问 令 牌 的 规范 (参见 http://tools.ietf.org/ 
we/oauth/draft-ietf-oauth-v2-http-mac/) : 使 用 访问 令 牌 时 必须 计算 消息 认证 码 (message 


authentication code，MAC) ， 将 访问 令 牌 与 密 钥 的 持 


凭证 一 起 使 用 。 




















access_ token l 
资源 服务 器 











图 16-4, 使 用 访问 令 牌 进行 资源 访问 
access_token 表示 一 个 权限 的 授予 ， 由 资源 服务 器 用 于 获取 请 求 者 的 信息 ， 也 就 是 执行 次 





注 1: 参见 RFC 6750。 





源 的 授权 策略 。 这 个 概念 听 起 来 很 含糊 ， 但 是 我 们 稍 后 会 回 到 这 个 话题 ， 给 出 访问 令 牌 及 
其 包含 信息 的 具体 示例 。 我 们 还 将 了 解 到 ， 基 于 ASP.NET 的 资源 服务 器 如 何 从 请 求 消息 
中 获取 令 牌 ,将 其 转换 为 用 户 身份 和 授权 信息 。 


要 将 访问 令 牌 绑 定 到 请 求 消息 ， 推 荐 做 法 是 使 用 Authorization 标 头 ， 将 标 头 值 设 为 Bearer 
方案 : 


GET https://storecode.example/resource HTTP/1.1 
Authorization: Bearer the.access.token 


这 种 推荐 做 法 使 用 第 1 章 介 绍 的 通用 的 HTTP 身份 认证 框架 。 的 确 ， 我 们 也 可 以 在 
application/x-www-form-urlencoded 正文 中 ， 或 者 请 求 URI 的 查询 字符 串 中 发 送 访问 令 
牌 , 但 这 些 不 是 推荐 的 做 法 。 在 请 求 URI 中 使 用 请 求 令 牌 的 做 法 尤为 不 妥 ， 因 为 请 求 URI 
通常 都 记录 在 日 志 中 ， 很 容易 遭 到 泄露 。 


16.3 ”获得 访问 令 牌 

客户 端 应 用 程序 可 以 向 令 牌 端点 (token end-point) 请 求 获得 令 牌 ， 令 牌 端点 是 认证 服务 器 
一 部 分 (参见 图 16-5) :。 令 牌 请 求 包 括 一 个 权限 授予 (authorization grant), ， 权 限 授予 是 
一 个 抽象 概念 ， 表 示 认 证 决定 所 依据 的 信息 。 权 限 授 予 可 以 有 多 种 实现 。 


























POST (client authn, grant info) 
200 (access_token, ...) 


授权 服务 器 


access_ token 


资源 服务 器 


























图 16-5: 使 用 认证 服务 器 的 令 牌 端点 获得 访问 令 牌 


在 简单 场景 中 ， 客 户 端 自 发 访问 资源 服务 器 (没有 用 户 介 入 )， 权 限 授予 可 以 只 是 客户 端 身份 
fa. TE OAuth 2.0 术语 中 ， 这 称 为 客户 端 凭据 授予 (client credential grant) 流 一 一 授权 完全 基 
于 客户 端的 身份 信息 。 这 个 情况 要 求 客户 端 是 保密 类 型 的 一 一 即 : 持 有 分 配 的 client_secret。 














如 果 有 用 户 介入 ， 权 限 授予 可 以 基于 用 户 的 密码 凭据 ， 这 一 凭据 由 用 户 提供 给 客户 端 ， 如 








TEL: 隐 式 流 是 这 一 规则 的 例外 ， 不 从 令 牌 端点 获取 令 牌 。 
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16-6 所 示 。 





POST (client authn, grant info) 


200 (access_token, ...) 


access_ token 














16-6: 基于 用 户 的 密码 凭据 获得 访问 令 牌 


在 OAuth 2.0 框架 中 ， 这 种 情况 称 为 资源 所 有 者 密码 凭据 授予 (resource owner password 
credentials grant) io WARR, OAuth 2.0 提供 这 种 支持 似乎 并 不 合理 ， 因 为 其 目标 之 一 
正 是 避免 这 种 凭据 泄露 。 然 而 ， 在 某 些 场景 中 ， 这 种 方式 是 合理 的 ， 尤 其 是 当 用 户 在 客户 
端 应 用 程序 中 具有 很 高 的 信任 度 时 〈 如 企业 应 用 场景 )。 首 先 ， 在 OAuth 2.0 中 ， 客 户 端 应 
用 程序 并 不 需要 保存 密码 ， 用 于 每 个 请 求 ， 而 只 是 将 密码 用 于 请 求 访 癌 令 牌 ， 然 后 便 可 将 
密码 立即 移 除 。 因 此 ， 如 果 用 户 修改 了 密码 ， 访 问 令 牌 可 能 还 是 有 效 的 。 这 种 权限 授予 类 
型 的 另 一 个 优点 是 实现 较为 简单 ， 特 别 是 当 客 户 端 是 本 地 移动 应 用 程序 时 。 


另 一 个 方法 是 使 用 授权 码 ， 表 示 用 户 无 需 使 用 密码 即 可 执行 的 委托 授权 。 这 种 方法 称 为 授 
权 码 授予 (authorization code grant) 流 ， 将 在 下 一 节 介 绍 。 





















































要 获得 令 牌 ， 我 们 可 以 向 令 牌 端点 URI 发 送 一 个 POST 请 求 ， 请 求 正 文 为 类 型 为 
application/x-www-form-urlencoded， 其 中 包含 权限 授予 类 型 及 其 值 。 例 如 ， 对 授权 码 授 
Pii, PAAA authorization_code， 授 予 值 为 授权 码 。 


























POST https://authzserver .example/token_endpoint HTTP/1.1 
Content-Type: application/x-www-form-urlencoded 
Host: authzserver.example 


grant_type=authorization_code& 
code=the. authorization. code 


如 果 客 户 端 是 保密 的 (客户 但 持 有 分 配 的 cLient_secret)， 那 么 这 个 令 牌 请 求 还 必须 包含 
客户 端 身份 验证 信息 。OAuth 2.0 框架 定义 了 两 种 提供 身份 验证 信息 的 方式 : 


。 使 用 BasicHTTP 身 份 验证 方案 ,其 中 client_id 和 client_secret 分 别 用 做 用 户 名 和 密码 ， 
。 将 client_id 和 client_secret 作为 字段 插入 令 牌 请 求 正 文 。 
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如 果 令 有 牌 请 求 成 功 ， 那 么 响应 消息 会 带 有 application/json 正文 ， 其 中 包含 访问 令 牌 的 
值 、 类 型 (例如 : bearer) 和 有 效 期 。 


HTTP/1.1 200 OK 
Content-Type: application/json; charset=utf-8 
Cache-Control: private, max-age=0, must-revalidate 


{"access_token":"the.access.token","token_type":"bearer", "expires_in":3600, 
. other info ...} 


16.4 授权 码 授予 


使 用 授权 码 授予 ， 用 户 不 向 客户 端 提 供 自己 的 身份 信息 ， 就 可 以 将 受 限 的 授权 委托 给 一 个 
客户 端 应 用 程序 。 用 户 通过 一 个 用 户 代理 〈 例 如 : Web 浏览 器 或 Web View)， 直 接 与 授权 
服务 器 的 授权 端点 进行 交互 。 授 权 码 授予 流 的 第 一 步 是 客户 端 应 用 程序 将 用 户 代理 重 定向 
到 授权 端点 (参见 图 16-7)。 客 户 端 使 用 授权 端点 请 求 URI 的 查询 字符 串 ， 插入 一 组 授权 
请 求 参数 : 




















https://authzserver .example/authorization_endpoint? 
client_id=the.client.id& 
scope=user+repo& 
state=crCMc3d0acGdDiNnxXJigpQ%3d%3d& 
response_type=code& 
redirect_uri=https%3a%2f%2fclient.example%2fcallback& 





GET (response_type, client_id, redirect_uri, scope, state) 


POST (client authn, grant info) 
200 (access_token, ...) 


access_ token o 
资源 服务 器 

















图 16-7: 从 授权 服务 器 的 授权 端点 请 求 授权 授予 


例如 ， 参 数 response_type 定义 了 要 请 求 的 权限 授予 ， 因 为 授权 端点 可 以 用 于 不 同 的 令 牌 
获取 流 ， 参 数 scope 描述 了 要 请 求 的 授权 特征 。 a 求 后 ， 授权 服务 器 开始 进行 协议 
外 (out-of-protocol) 用 户 交 互 ， 目 的 是 对 用 户 进行 身份 验证 ， 可 能 还 要 获取 用 户 对 客户 端 
所 请 求 授 权 的 同意 。 
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协议 外 身份 验证 和 许可 


POST (client authn, grant info) 
200 (access_token, ...) 




















16-8: 用 户 与 授权 端点 之 间 的 直接 交互 ， 以 进行 身份 验证 和 授权 许可 


OAuth 2.0 协议 没有 定义 用 户 身份 验证 协议 ， 授 权 服 务 器 可 以 自由 选择 最 合适 的 身份 验证 
协议 ， 既 可 以 使 用 简单 的 基于 表单 的 用 户 名 和 密码 方案 ， 也 可 以 使 用 分 布 式 联邦 协议 。 





在 成 功 进行 身份 验证 之 后 ， 授 权 服 务 器 还 可 以 询问 用 户 ， 是 否 同意 客户 端 应 用 程序 请 求 的 
授权 。 在 这 里 ， 授 权 服 务 器 会 使 用 客户 端 在 注册 过 程 中 提供 的 描述 信息 〈 例 如 : 应 用 程序 
名 称 、 商 标 和 主 URI) ， 为 用 户 提供 更 多 信息 。 最 后 ， 授 权 服 务 器 使 用 请 求 参数 redirect_ 
uri fil, HRA AT URI, AP REM EIA Pom AR. FE el 16-9 所 
示 ， 重 定向 URI 如 下 所 示 : 




















Fh 





https://client.example/callback? 
code=52...e4& 
state=cr...3D 


出 于 安全 考虑 ， 客 户 端 使 用 的 重 定向 URI 集合 应 该 预先 进行 配置 。T.AS 正 是 这 样 实现 的 ， 
从 图 16-3 中 可 以 看 到 ， 每 个 客户 端 都 关联 到 一 组 重 定向 URI. 





302 (state, code) | (state, access_token, ...) 


POST (client authn, grant info) 
200 (access_token, ...) 


access_ token 

















16-9: 包含 授权 授予 的 授权 端点 响应 
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OAuth 2.0 框架 定义 的 最 后 一 个 令 牌 获取 流 是 隐 式 赋予 (implicit grant)， 隐 式 赋 予 直 接 在 授 
权 端 点 的 响应 中 返回 访问 令 牌 。 这 是 唯 个 不 从 令 牌 端点 返回 访问 令 牌 的 OAuth 2.0 流 。 























0Auth 2.0 授权 码 流 示例 


位 于 https://github.com/webapibook 的 OAuth2.Demos.AuthzCodeGrant 程序 库 ， 提 供 一 
个 自 托 管 的 OAuth 2.0 客户 痛 榨 制 台 应 用 程序 ， 其 中 使 用 了 授权 三 流 。 这 个 应 用 程序 
预先 配置 为 使 用 GitHub API v3， 但 是 也 可 以 使 用 其 他 授权 服务 器 和 资源 服务 器 。 要 使 
用 GitHub API 运行 这 个 示例 程序 ， 你 可 以 在 GitHub 的 “account settings” 中 provision 
一 个 “developer application”， 在 代码 中 为 client_id 和 client_secret 赋值 。 这 个 示例 
受到 的 评价 颇 高 ， 而 且 可 以 用 于 捕获 OAuth 2.0 协议 消息 。 











16.5 ”范围 


我 们 前 面 介绍 过 ，OAuth 2.0 的 目标 之 一 是 ， 支 持 客 户 端 使 用 最 终 由 用 户 委 托 的 受 限 授 权 ， 
进行 资源 访问 。 为 此 ，OAuth 2.0 框架 使 用 范围 (scope) 这 个 概念 ， 定 义 这 些 授权 的 限制 
条 件 。 范 围 的 正式 定义 是 一 列 以 空格 分 隔 的 标识 符 ， 每 个 标识 符 定 义 一 个 授权 类 型 。 例 
如 ，GitHub Web API 使 用 的 一 些 范 围 定 义 符 有 : 























。 user 授权 客户 端 进行 用 户 个 人 资料 信息 的 读 / 写 操作 ， 
。 user:email 授权 客户 端 读 取 用 户 的 电子 邮件 ; 
e public_repo; 授权 客户 端 进行 用 户 的 公共 存储 库 的 读 / SERVE. 





因此 ， 字 符 串 user:email public_repo 定义 了 一 个 范围 ， 具 有 读 取 电子 邮件 和 读 / 写 存储 
库 的 授权 。 


通常 情况 下 ， 这 些 范 围 标识 符 及 其 相关 语义 是 由 资源 服务 器 定义 的 。 范 围 标识 符 通常 还 具 
有 相关 的 人 工 可 读 的 描述 ， 在 向 用 户 展 示 授 权 许可 表格 时 使 用 。 


举 个 例子 ，T.AS 中 的 范围 由 如 下 字段 定义 (参见 图 16-3) : 












































。 范围 标识 符 ; 
。 范围 的 显示 名 称 和 描述 ， 用 于 与 人 类 交互 ， 例 如 请 求 获得 用 户 的 授权 许可 
。 允许 请 求 这 一 范围 的 一 列 客户 端 。 











一 个 客户 端 可 以 使 用 的 范围 可 能 是 受 限 的 ， 如 图 16-3 所 示 。 

范围 在 协议 中 广泛 使 用 ， 通 常 通过 一 个 scope 参数 传人 。 当 使 用 客户 端 凭证 或 资源 所 有 者 
密码 授予 时 ， 客 户 端 可 以 在 发 送 给 令 牌 端点 的 令 牌 请 求 中 包括 这 个 scope 参数 ， 以 定义 请 
求 授 权 。 与 此 类 似 ， 当 使 用 授权 码 或 者 隐 式 授权 流 时 ， 客 户 端 可 以 在 发 送 给 授权 端点 的 授 
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权 请 求 中 包括 scope 参数 。 授 权 服 务 器 可 以 基于 用 户 的 同意 ， 返 回 一 个 不 同 于 所 请 求 的 授 
权 范 围 。 因 此 ， 令 牌 响应 中 也 可 以 包含 scope 参数 ， 以 通知 客户 端 所 授予 的 授权 。 


16.6 ”前 通道 与 后 通道 


要 更 好 地 理解 OAuth 2.0 框架 ,我 们 需要 认识 到 ， 客 户 端 以 两 种 不 同 的 方式 与 授权 服务 器 
进行 通信 : 后 通道 (back ural 方式 和 前 通道 (front channel) 方式 。 后 通道 是 客户 端 
与 令 牌 端点 之 间 的 直接 通信 ， 如 图 6-5 所 示 。 而 前 通道 是 客户 端 aati 点 之 间 ， 通 过 用 
户 代理 ， 基 于 HTTP 重 定向 ， 进 行 间接 通信 (参见 图 16-7)。 因 此 ， 前 通道 具有 一 些 明 显 
的 局 限 性 。 前 通道 基于 重 定向 ， 因 此 对 可 以 使 用 的 HITP 功能 有 所 限制 : 请 求 方 法 必须 是 
GET， 请 求 信息 必须 位 于 请 求 URI 中 ， 即 URI 的 查询 字符 串 。 























https://authz_server .example/authorization_endpoint? 
client_id=the.client.id& 
scope=user+repo& 
state=crCMc3d0acGdDiNnXJigpQ%3d%3d& 
response_type=code& 
redirect_uri=https%3a%2f%2fclient.example%2fcallback& 


此 外 ， 响 应 永远 是 一 个 重 定向 ， 因 此 响应 信息 也 要 在 重 定向 请 求 URI 中 传递 


https://client.example/callback? 
code=52...e4& 
state=cr...3D 


如 果 出 现 错误 ， 我 们 不 能 使 用 标准 的 HTTP 状态 码 (响应 永远 是 一 个 重 定向 )， 而 是 在 
URI 的 查询 字符 串 中 使 用 error 和 error_description 参数 ， 以 此 传递 错误 信息 


https://client.example/callback? 
error=access_denied& 
error_description=authorization+not+granted 


而 且 ， 前 通道 通过 用 户 代理 运行 ， 如 果 传 输 客 户 端 凭证 〈cLient_secret) ， 会 对 用 户 可 见 ， 
因此 无 法 安全 传输 客户 端 凭证 。 因 此， 在 所 有 前 通道 请 求 中 ， 客 户 端 会 进行 标识 (发送 
cLient_id) ， 但 是 不 会 进行 身份 验证 client_id 是 公开 的 信息 ， 攻 击 者 很 容易 伪造 出 有 效 
的 授权 请 求 。 


最 后 ， 前 通道 还 无 法 确保 客户 端 发 送 给 授权 服务 器 的 请 求 ， 和 相应 的 响应 之 间 的 相关 性 ， 
容易 受到 CSRF (Cross-Site Request Forgery， 跨 站 请 求 伪造 ) 攻击 。 在 跨 站 请 求 伪 造 攻 击 
中 ， 一 个 第 三 方 恶意 站 点 会 让 用 户 的 浏览 器 向 客户 端 发 送 一 个 请 求 ， 模 拟 一 个 OAuth 2.0 
前 通道 响应 。 使 用 这 种 技术 ， 攻 击 站 点 可 以 控制 客户 端 使 用 的 访问 令 牌 一 一 例如 ， 使 用 分 
发 给 攻击 者 帐户 的 授权 码 。 








为 了 解决 这 个 问题 OAuth 2.0 框架 在 请 求 和 响应 中 都 使 用 了 一 个 状态 参数 ， 以 确保 其 





370 | 第 16 章 


相关 性 。 客 户 端 创 建 一 个 随机 的 状态 值 ， 将 这 个 值 包含 在 通过 前 通道 发 送 的 请 求 中 。 最 
后 ， 授 权 服 务 器 会 在 通过 前 通道 返回 的 响应 中 包含 同样 的 状态 值 。 通 过 这 种 机 制 ， 客 户 端 
可 以 把 收 到 的 响应 与 之 前 发 送 的 请 求 联系 起 来 。REFC 6819—OdAuth 2.0 Threat Model and 
提供 了 关于 如 何 有 效 使 用 这 种 保护 机 制 的 更 多 信息 。 











Security Consideration 








考虑 到 这 些 限 制 和 问题 ， 你 可 能 会 奇怪 ， 为 什么 人 们 还 在 使 用 前 通道 。 主 要 原因 是 ， 通 过 
前 通道 ， 授 权 服 务 器 可 以 和 用 户 直接 进行 交互 ， 不 需要 任何 客户 端的 干预 和 出 现 。 图 16-8 
展示 了 授权 服务 器 如 何 使 用 这 一 功能 ， 对 用 户 进行 身份 验证 ， 并 获得 用 户 的 授权 许可 。 


另 一 方面 ， 后 通道 将 客户 端 与 令 牌 端点 直接 连接 ， 二 者 之 间 的 通信 可 以 不 限于 HTTP EE 
向 。 例 如 ， 客 户 端的 令 牌 请 求 是 一 个 HTTP 的 POST 请 求 ， 参 数位 于 请 求 正 文中 ， 响 应 可 能 
使 用 HTTP 状态 码 代 表 不 同 的 错误 条 件 (例如 ，469 表示 错误 请 求 ， 或 者 401 表示 客户 端 
身份 验证 失败 )。 


如 果 客 户 端 持 有 client_secret (保密 客户 端 )， 就 必须 在 后 通道 中 使 用 client_secret， 对 
自己 进行 身份 验证 。 对 此 ，OAuth 2.0 框架 推荐 使 用 HTTP 基础 认证 方案 ， 将 用 户 名 和 密 
码 分 别 替 换 为 client_id 和 client_secret; 








POST https://authz_server.example/token_endpoint HTTP/1.1 
Content-Type: application/x-www-form-urlencoded 

Authorization: Basic dGhLLmNsaWVudC5pZDpQaGUuY2xpZW50LnNLY3IJLdA== 
Host: authz_server.example 


grant_type=authorization_code& 
code=the. authorization. code 





后 通道 和 前 通道 
其 实 OAuth 2.0 RFC 文 档 并 没有 使 用 前 通道 和 后 通道 这 两 个 词 。 我 们 从 SAML 术语 (参见 
https://www.oasis-open.org/committees/download.php/21111/saml-glossary-2.0-0s.htm]l) 
中 借用 了 这 两 个 词 ， 因 为 这 两 个 词 可 以 很 好 地 帮助 我 们 描述 客户 端 与 授权 服务 器 进行 
通信 的 不 同方 式 。 


A 
16.7 刷新 令 牌 

访问 令 牌 属于 敏感 信息 ， 其 使 用 生存 期 应 该 受到 限制 。 为 了 解决 这 个 问题 ，OAuth 2.0 HE 
架 定义 了 刷新 令 牌 ， 用 于 获取 新 的 访问 令 牌 。 当 客户 端 向 令 牌 端点 发 出 请 求 ， 使 用 权限 授 
予 交 换 访问 令 牌 时 ， 得 到 的 响应 也 可 能 包含 一 个 刷新 令 牌 。 











HTTP/1.1 200 OK 
Content-Type: application/json; charset=utf-8 
Cache-Control: private, max-age=0, must-revalidate 


{"access_token":"the.access.token","token_type":"bearer", "expires_in":3600, 
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"refresh_token":"the.refresh.token"} 


客户 端 应 用 程序 可 以 使 用 这 个 刷新 令 牌 ， 获 取 新 的 访问 令 牌 一 一 例如 ， 当 旧 令 牌 即将 过 期 
时 。 这 一 操作 也 在 令 牌 端点 完成 ， 请 求 中 的 grant_type 字段 包含 refresh_token 的 值 : 





POST https://authzserver.example/token_endpoint HTTP/1.1 
Content-Type: application/x-www-form-urlencoded 
Host: authzserver.example 


grant_type=refresh_token& 
refresh_token=the. refresh. token 


成 功 的 响应 将 包含 新 的 访问 令 牌 和 令 牌 生存 期 ， 还 可 以 包含 一 个 新 的 刷新 令 牌 。 

使 用 刷新 令 牌 对 客户 端 应 用 程序 提出 了 更 多 的 需求 ， 客 户 端 应 用 程序 必须 安全 存储 这 一 新 信 
息 ， 监 控 访 问 令 牌 的 生存 期 ， 定期 对 令 牌 进行 更 新 。 但 是 ， 刷 新 令 牌 有 具有 一 些 有 用 的 属性 。 
从 安全 的 角度 来 看 ， 缩 短 访问 令 牌 的 生存 期 ， 限 制 了 恶意 访问 这 一 信息 可 能 造成 的 后 果 。 
从 实现 和 优化 的 角度 看 ， 使 用 刷新 令 牌 ， 系 统 可 以 采取 混合 方式 ， 刷 新 令 牌 使 用 可 撤销 的 
生成 物 令 牌 ， 指 向 存储 库 中 的 一 个 条 目 ， 而 访问 令 牌 使 用 短 时 效 的 不 可 撤销 的 状态 断言 。 
采用 这 种 方式 ， 访 问 令 牌 的 验证 不 需要 访问 存储 库 ， 更 容易 进行 扩展 。 虽 然 访问 令 牌 是 不 
可 撤销 的 ， 但 是 其 缩短 的 生存 期 弥补 了 这 一 缺陷 。 另 一 方面 ， 你 可 以 在 存储 库 中 删除 相关 
条 目 或 将 其 标记 为 无 效 ， 很 容易 地 撤销 刷新 令 牌 。 


16.8 ”资源 服务 器 和 授权 服务 器 


OAuth 2.0 框架 明确 定 指出 了 服务 器 端的 两 个 职责 : 






























































。 资源 服务 器 (resource server) 提供 访问 受 保护 资源 的 接口 ， 是 访问 令 牌 的 使 用 者 ， 
。 授权 服务 器 (authorization server) 的 职责 众多 ， 其 中 之 一 是 颁发 访问 令 牌 ， 用 于 访问 受 
保护 的 资源 。 


这 并 不 是 说 资源 服务 器 和 授权 服务 器 必须 是 两 个 独立 的 实体 。 这 两 个 角色 完全 可 以 由 同一 
个 物理 机 器 以 及 同样 的 软件 组 件 实现 。 但 是 ，OAuth 2.0 框架 的 确 支 持 分 离 的 架构 ， 其 中 
授权 服务 器 由 单独 的 软件 组 件 运 行 ( 例 如; Thinktecture 授权 服务 器 ) 。 资 源 服务 器 甚至 可 
以 依赖 由 另 一 个 实体 运行 的 外 部 授权 服务 器 〈 例 如 : Windows Azure Active Directory) 。 























虽然 支持 这 些 分 离 的 架构 ， 但 是 OAuth 2.0 框架 并 没有 指定 独立 的 资源 服务 器 和 授权 服务 
器 应 当 如 何 协作 。OAuth 2.0 框架 对 于 一 些 方面 (如 访问 令 牌 格式 和 验证 过 程 ) 未 加 定义 ， 
我 们 必须 针对 每 个 场景 进行 定义 。 请 注意 ， 从 用 户 或 客户 端的 角度 ， 这 些 具体 实现 不 会 产 
生 任 何 影响 ， 因 为 访问 令 牌 本 来 就 对 用 户 或 客户 端 不 透明 。 

















另外 ，OAuth 2.0 框架 也 没有 定义 ， 授 权 服 务 器 通过 访问 令 牌 要 传递 给 资源 服务 器 哪些 信 
息 。 最 直接 的 做 法 是 ， 用 访问 令 牌 表示 令 牌 请 求 和 相关 授权 ， 包 括 的 信息 有 : 
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。 资源 所 有 者 标识 〈《 如 果 客 户 端 不 是 自发 进行 访问 ) ; 

。 发 起 请 求 的 客户 端 ， 由 其 client_id 标识 ， 

。 所 请 求 的 授权 范围 ， 由 scope 字符 串 标 识 。 

与 访问 令 牌 相关 的 信息 还 应 该 包括 其 时 间 有 效 期 ( 令 牌 并 非 永久 有 效 ) 以 及 令 牌 的 受众 ， 
也 就 是 令 牌 发 往 的 资源 服务 器 的 一 些 标识 信息 。 

例如 ，TAS 使 用 JWT 格式 标识 访问 令 牌 。 示 例 16-1 展示 了 这 种 JWT 令 牌 的 有 效 载 倚 ， 其 中 有 : 
。 sub 声明 (其 中 包含 用 户 唯一 标识 符 ) 和 role 声明 (其 中 包含 附加 的 用 户 声明 ) ; 

e client_id 声明 ， 其 中 包含 客户 端 应 用 程序 标识 ， 

。 scope 声明 ， 其 中 包含 所 授予 的 授权 范围 。 

令 牌 有 效 载 答 还 包含 令 牌 颁发 者 的 标识 (iss 声明 )， 以 及 令 牌 针对 的 目标 或 受众 (aud 声明 )。 


示例 16-1: 由 Thinktecture 授权 服务 器 颁发 的 一 个 访问 令 牌 的 JWT 有 效 载 荷 
{ 
































"exp": 1379284015, 


"aud": "http://resourceserver.example", 

"iss": "http://authzserver.example", 

"role": [ 
"fictional_character", 
"student" 

], 

"client id": "client2", 

"scope": [ 

"scopel", 


"scope2" 


J; 
"nbf": 1379280415, 
"sub": "Alice" 


} 
与 示例 16-1 中 的 role 声明 一 样 ， 用 户 标 识 也 可 以 不 限于 简单 的 标识 符 ， 很 好 地 契合 了 第 
15 章 中 介绍 的 声明 模型 。 


16.9 在 ASP.NET Web API 中 处 理 访 问 令 牌 


我 们 在 15.3.8 节 介 绍 过 ，Katana 项 目 提供 一 组 身份 认证 中 间 件 类 ， 其 中 的 OAuthBearerAut 
henticationMiddleware 实现 了 OAuth 2.0 Bearer 认证 方案 。0AuthBearerAuthenticationMid 
dleware 的 行为 通过 OAuthBearerAuthenticationOptions 类 进行 配置 (参见 图 16-10)。 当 接 
收 到 一 个 请 求 时 ， 相 关 的 身份 验证 处 理 程序 会 执行 以 下 步骤 。 


(1) 获取 令 牌 。 如 果 请 求 包含 方案 为 Bearer 的 Authorization 标 头 ， 那 么 使 用 该 标 头 值 作为 
访问 令 牌 。 否 则 ， 身 份 验 证 方法 不 返回 任何 身份 信息 。 

(2) 获取 身份 认证 票据 。 从 消息 获得 令 牌 之 后 ，0ptions.AccessTokenFormat.Unprotect 方法 
从 访问 令 牌 获取 一 个 身份 验证 票据 。 正 如 我 们 之 前 看 到 的 ， 这 个 票据 既 包含 基于 声明 的 
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身份 信息 ， 也 包含 附加 的 身份 验证 属性 。 


(3) 验证 身份 验证 票据 。 最 后 一 步 ， 检 查 身 份 验证 票据 的 有 效 性 。 


在 处 理 程序 最 后 ， 如 果 所 有 的 步骤 都 执行 成 功 ， 那 么 请 求 的 访问 令 牌 会 
息 返 回 。 
行 定 制 。 





也 可 以 验证 和 修改 获取 到 的 身份 信息 。 


在 默认 情况 下 ，Katana 使 用 一 个 定制 的 访问 令 牌 格式 ， 在 其 自己 的 授权 服务 器 中 使 用 。 但 是 ， 
通过 修改 0ptions.AccessTokenFormat， 你 也 可 以 对 Katana 进行 配置 ， 使 其 接受 基于 JWT 的 访 
问 令 牌 。Katana 的 UseJwtBearerAuthentication 扩展 方法 就 实现 了 这 一 功能 ， 过 程 如 下 。 


通过 Options.Provider 和 Options.AccessTokenProvider , 


例如 : 如 果 定 义 了 0ptions.Provider， 你 可 以 从 消息 的 其 


























转换 为 一 个 身份 信 
你 可 以 对 之 前 的 步骤 进 
也 部 分 获取 访问 令 牌 ， 














(1) 使 用 一 个 JwtBearerAuthenticationOptions 参数 ， 其 中 包含 了 如 何 验证 JWT 令 牌 的 信 


息 ， 其 中 有 : 允许 的 受众 和 签名 验证 信息 。 





(2) 在 内 部 创建 一 个 使 用 JwtFormat 配置 的 OAuthBearerAuthenticationOptions, JwtFormat 
是 一 个 使 用 JWT 格式 的 ISecureDataFormat 实现 。 





。 使 用 OAuthBearerAuthenticationOptions, 


图 16-10 展示 了 这 一 过 程 中 用 到 的 类 。 示 例 16-2 展示 了 如 何 利 用 


基于 Katana 的 资源 服务 器 


， 操 作 如 下 : 


。 将 AllowedAudiences 属性 配置 为 资源 服务 器 的 URI; 
e 将 IssuerSecurityTokenProviders 属性 配置 为 授权 服务 器 的 对 称 签名 密 钥 。 











注册 OAuthBearerAuthenticationMiddleware, 


一 扩展 方法 ， 配 置 一 个 
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16-10: 使 用 基于 JWT 的 访问 令 牌 的 类 
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示例 16-2: 将 一 个 基于 Katana 的 资源 服务 器 配置 为 使 用 T.AS 
config.Filters.Add(new HostAuthenticationFilter("Bearer")); 


app.UseJwtBearerAuthentication(new JwtBearerAuthenticationOptions 


{ 


AllowedAudiences = new [] 


"http://resourceserver .example" 


} 


IssuerSecurityTokenProviders = new [] 
{ 
new SymmetricKeyIssuerSecurityTokenProvider( 
"http://authzserver.example", 
"the.authorization.symmetric.signature.key") 


}, 
Realm = "resourceserver.example", 


AuthenticationMode = AuthenticationMode. Passive 
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16.10 OAuth 2.0 与 身份 验证 


从 RFC 6749 的 文档 名 (OAuth 2.0 授权 框架 ) 就 可 以 看 出 ，OAuth 2.0 关注 的 主要 内 容 是 
授权 ， 而 非 身份 验证 。OAuth 2.0 的 主要 目标 是 ， 支 持 客 户 端 应 用 程序 以 自发 或 代表 用 户 
的 方式 ， 访 问 Web API 提供 的 资源 子 集 。 但 是 ，OAuth 2.0 框架 的 实现 也 可 以 提供 某 些 形 
式 的 身份 验证 功能 。 


正如 我 们 在 本 章 开头 介绍 的 ， 由 客户 端 应 用 程序 向 资源 服务 器 发 起 的 请 求 ， 包 含 一 个 访问 
令 牌 。 这 个 令 牌 的 主要 目的 是 向 资源 服务 器 证 明 ， 令 牌 的 持 有 者 ( 即 发 起 请 求 的 客户 端 应 
用 程序 ) 得 到 了 用 户 的 授权 ， 可 以 访问 受 保护 的 资源 。 要 实现 这 一 目的 ， 通 常 的 做 法 是 使 
用 访问 令 牌 完成 如 下 功能 : 

。 对 发 送 请 求 的 客户 端 应 用 程序 进行 身份 验证 ， 

。 对 进行 授权 的 用 户 进行 身份 验证 ; 

。 定义 授权 范围 。 











图 16-11 描绘 了 这 一 身份 验证 场景 ， 甚 中 授权 服务 器 是 身份 信息 提供 方 ， 资 源 服务 器 是 转 
发 方 ， 客 户 端 和 用 户 都 是 身份 信息 的 主体 。 例 如 ，T.AS 颁发 的 JWT 令 牌 〈 参 见 示例 16-1) 
恰好 包含 这 三 个 信息 : client_id、 用 户 声明 (role 和 sub) 和 授权 范围 。 还 需要 注意 的 
是 ， 使 用 Katana 中 间 件 时 ， 访 问 令 牌 信息 会 转换 为 一 个 用 户 身份 对 象 ， 传 递 到 上 层 。 但 
是 ,我们 前 面 介绍 过 ，OAuth 2.0 框架 没有 定义 访问 令 牌 的 格式 和 信息 ， 由 具体 实现 决定 
这 些 细 市 。 如 有 果 在 一 个 OAuth 2.0 的 实现 中 ， 访 问 令 牌 只 包含 授权 资源 和 HITP 方法 ， 而 
没有 任何 关于 客户 端 或 用 户 的 信息 ， 也 是 完全 可 能 的 。 因 此 ， 在 大 多 数 时 候 访问 令 牌 也 是 
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一 个 身份 验证 令 牌 ， 向 资源 服务 器 提供 客户 端 和 用 户 的 身份 验证 信息 ， 但 是 这 要 取决 于 记 
架 的 具体 实现 。 


IHI 








页 发 二 
TRAJ 。 授权 服务 器 


资源 服务 器 


























16-11: 使 用 访问 令 牌 向 资源 服务 器 提供 客户 端 和 用 户 的 身份 验证 


OAuth 2.0 框架 也 可 以 用 作 另 一 种 身份 验证 的 基础 : 向 客户 端 应 用 程序 提供 用 户 的 身份 验证 。 
客户 端 可 以 使 用 包含 用 户 身份 信息 的 上 下 文 相关 资源 〈 称 作用 户 信 息 资 源 )， 对 用 户 进行 身 
份 验证 。 例 如 ， 在 GitHub API v3 中 ， 对 https://api.github.com/user 的 成 功 6ET 操作 会 返回 一 
个 资源 表示 ， 其 中 包含 客户 端 所 使 用 的 访问 令 牌 代表 的 用 户 的 姓名 和 电子 邮件 地 址 。 客 户 端 
应 用 程序 可 以 借 此 获得 资源 服务 器 和 授权 服务 器 宣称 的 用 户 身 份 信息 (参见 图 16-12) 。 









































身份 信息 提供 方 


授权 服务 器 


身份 信息 主体 


资源 服务 器 














16-12: 客户 端 使 用 受 保护 资源 验证 用 户 身份 


在 我 们 编写 这 本 书 时 ， 已 经 经 常 可 以 看 到 Web 应 用 程序 使 用 这 种 基于 OAuth 2.0 的 技术 ， 
向 社交 身份 信息 提供 方 ( 例 如 :Facebook 或 GitHub) 验证 用 户 的 身份 。 但 是 ， 这 种 做 法 存 
在 两 个 缺点 。 首 先 ， 这 种 做 法 依赖 上 下 文 相关 的 用 户 信息 资源 ， 而 这 种 资源 并 未 在 OAuth 
2.0 框架 中 定义 。 这 意味 着 我 们 必须 针对 每 个 不 同 的 资源 服务 器 进行 定制 。 甚 次， 最 重要 
的 是 ， 这 种 身份 验证 用 法 不 是 对 所 有 OAuth 2.0 框架 流 都 安全 一 一 具体 来 说 ， 对 使 用 公共 
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客户 端的 隐 式 流 和 授权 码 流 不 安全 。 例 如 ， 在 一 些 流 中 ， 客 户 端 应 用 程序 可 以 使 用 授权 码 
或 者 令 牌 ， 把 自己 作为 用 户 ， 在 另外 一 个 应 用 程序 中 进行 身份 验证 。 在 隐 式 流 中 ， 用 户 代 
理 直 接 把 令 牌 从 授权 端点 传递 到 客户 端 应 用 程序 。 在 接收 到 令 牌 后 ， 一 个 恶意 客户 端 可 以 
向 另 一 个 客户 端 提供 这 个 令 牌 ， 将 自己 伪装 成 用 户 。 当 第 二 个 客户 端 访问 这 个 用 户 信息 资 
源 时 ， 得 到 的 将 是 原始 用 户 的 身份 信息 。 




















OpenID Connect (http://openid.net/connect/) 规范 在 OAuth 2.0 框架 之 上 提供 一 个 身份 信息 
层 ， 致 力 于 解决 这 两 个 问题 。' 首先 ，OpenID Connect 规范 对 用 户 信 息 资 源 (在 这 个 规范 
中 称 为 UserInfo Endpoint) 的 概念 及 其 返回 的 标识 进行 了 标准 化 : 一 个 成 员 为 声明 的 JSON 
对 象 ，OpenID Connect 也 定义 了 这 些 声 明 的 含义 。 示 例 16-3 是 Google Userinfo 资源 (位 
于 https://www.googleapis.com/oauth2/v3/userinfo) 为 我 们 虚构 的 用 户 Alice 返回 的 声明 。 

















示例 16-3: Userlnfo 资源 返回 的 表示 


{ 
"sub": "104107606523710296052", 
"email": "alice4ddemos@gmail.com", 
"email_verified": true 


} 


OpenID Connect 还 扩展 了 OAuth 2.0 的 令 牌 响应 定义 ， 添 加 了 一 个 id_token 字段 (参见 示 
例 16-4), id_token 字段 的 值 是 一 个 签名 的 JWT 令 牌 ， 其 中 包含 用 户 声 明 ， 可 供 客户 端 使 
用 。 请 注意 ， 这 与 访问 令 牌 的 概念 相悖 ， 访 问 令 牌 对 客户 端 是 不 透明 的 。 示 例 16-5 展示 了 
A ID 令 牌 的 有 效 载 竺 ， 甚 中 包含 关于 用 户 的 身份 信息 声明 (email 声明 ) ， 但 也 包含 该 
令 牌 针对 的 受众 : aud FAHY, aud 声明 的 值 是 客户 端 应 用 程序 的 client_id。 这 个 aud 字段 
将 一 个 了 令 牌 绑 定 到 一 个 使 用 者 ， 以 防止 恶意 客户 端 在 其 他 客户 端 重用 这 个 令 牌 。 


示例 16-4: 包含 ID 令 牌 的 令 牌 响应 
{ 
"access_token" : "ya..8s", 
"token_type" : "Bearer", 
"expires_in" : 3599, 
"id_token" : "ey..0Q" 
} 


示例 16-5: 令 牌 响应 中 返回 的 ID 令 牌 有 效 载荷 
{ 
































"sub": "104107606523710296052", 
": "accounts.google.com", 
"email_verified": "true", 

"at_hash": "G_...hQ", 

"exp": 1380480238, 

"azp": "55...ve.apps.googleusercontent.com", 
"iat": 1380476338, 























TE 1: 虽然 名 为 OpenID Connect， 但 这 个 规范 更 类 似 OAuth 2.0， 而 非 经 典 的 OpenID 协议 。 
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"email": "alice4ddemos@gmail.com", 
"aud": "55...ve.apps.googleusercontent.com" 





OpenID Connect 授权 码 流 示例 


WebApiBook.Security 存储 库 位 于 https:/Wgithub.com/webapibook， 包 人 钨 一 个 自 托 管 的 
OpenID Connect 客户 癌 控 制 台 应 用 程序 ， 其 中 使 用 了 授权 代码 流 。 这 个 示例 程序 预先 
配置 为 使 用 谷歌 授权 服务 器 ， 但 是 也 可 以 使 用 其 他 的 OpenID Connect 实现 。 








通过 在 OAuth 2.0 之 上 添加 一 个 身份 信息 层 ，OpenID Connect 为 客户 端 应 用 程序 提供 了 一 
个 一 致 的 协议 ， 以 完成 以 下 功能 : 

。 获取 一 个 签名 的 身份 信息 声明 集合 ， 对 其 用 户 进行 身份 验证 ， 

。 获取 一 个 访问 令 牌 ， 使 客户 端 可 以 访问 代表 用 户 访问 受 保护 的 资源 。 

请 注意 ， 经 典 的 身份 信息 联邦 协议 (例如: SAML, WS-Federation 或 经 典 的 OpenID 协议 ) 
只 提供 第 一 个 功能 。 而 OAuth 2.0 框架 只 提供 第 二 个 功能 。 


16.11 基于 范围 的 授权 


使 用 OAuth 2.0 框架 时 ， 你 可 以 将 授权 决定 从 资源 服务 器 中 移 走 ， 在 授权 服务 器 中 实现 。 
我 们 之 前 介绍 过 ,访问 令 牌 有 与 其 相关 的 范围 ， 确 切 定义 了 将 什么 权限 授予 客户 端 。 因 
此 ， 在 这 种 情况 下 ， 资 源 服 务 器 就 只 需要 执行 令 牌 范围 中 定义 的 授权 决定 。 











第 15 章 中 介绍 的 Thinktecture.IdentityModel.45 程序 库 也 提供 一 个 定义 范围 的 授权 属性 
ScopeAttribute, ScopeAttribute 的 构造 国 数 参数 为 一 列 范围 标识 符 ， 只 有 当 相 关联 的 声 
明 用 户 对 象 的 范围 声明 与 这 些 标识 符 全 部 匹配 时 ， 请 求 才能 得 到 授权 。 
































示例 16-6 展示 了 ScopeAttribute 的 用 法 ， 其 中 POST 请 求 要 求 使 用 带 有 create 范围 标识 符 
的 访问 令 牌 ， 而 DELETE 请 求 要 求 使 用 带 有 delete 标识 符 的 访问 令 牌 。 


示例 16-6: 使 用 ScopeAttribute 


public class ScopeExampleResourceController : ApiController 


{ 

public HttpResponseMessage Get() 

{ 
return new HttpResponseMessage 
{ 

Content = new StringContent("resource representation") 

}; 

} 


[Scope("create")] 
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public HttpResponseMessage Post() 


{ 
return new HttpResponseMessage( ) 
{ 
Content = new StringContent("result representation") 
}; 
} 


[Scope("delete")] 
public HttpResponseMessage Delete(string id) 


{ 
} 


return new HttpResponseMessage(HttpStatusCode.NoContent) ; 


} 


16.12 ”小结 


本 章 介 绍 了 OAuth 2.0 授权 框架 ， 包 括 其 所 用 协议 和 模式 。OAuth 2.0 授权 框架 有 几 个 值得 
强调 的 功能 。 首 先 ，OAuth 2.0 框架 引入 了 一 个 模型 ， 对 用 户 、 客 户 端 和 资源 服务 器 进行 了 
明确 的 区 分 。 当 这 三 个 角色 分 属 不 同 的 信任 域 时 ， 这 种 概念 区 分 变 得 尤为 重要 ， 而 且 将 极 

影响 我 们 对 基于 Web 系统 进行 安全 建 模 的 方式 。OAuth 2.0 还 引入 了 授权 服务 器 的 概念 ， 
将 其 定义 为 一 个 实体 ， 负 责 颁发 和 管理 客户 端 (代表 用 户 ) 用 于 访问 资源 的 访问 令 牌 。 


在 我 们 编写 这 本 书 时 ， 大 部 分 OAuth 2.0 实现 所 使 用 的 身份 验证 服务 器 ， 都 与 使 用 其 服务 
的 资源 服务 器 相关 联 。 但 是 ， 有 一 些 项 目 ， 例 如 : Thinktecture 的 授权 服务 器 和 Windows 
Azure Active Directory， 正 在 开始 提供 可 以 用 在 多 种 上 下 文 ， 与 不 同 资源 服务 器 一 起 工作 
的 授权 服务 器 。OAuth 2.0 框架 也 提供 了 用 于 不 同 场景 的 具体 模式 和 协议 ， 既 支持 客户 端 
自发 访问 资源 (客户 端 凭 据 授 予 流 )， 也 支持 通过 前 通道 交互 进行 受 限 的 授权 委托 (授权 
码 授 予 流 )。 



































OAuth 2.0 还 是 新 的 OpenID Connect 协议 的 基础 。OpenID Connect 提供 了 非 集中 式 的 身份 
验证 功能 。 所 有 这 些 技术 为 我 们 提供 了 一 种 集成 的 方式 ， 解 决 Web API 中 存在 的 一 些 身份 
验证 和 授权 问题 。 

虽然 OAuth 2.0 框架 目前 得 到 了 极 大 的 支持 ， 但 是 也 受到 了 许多 的 批评 。 首 先 ，OAuth 2.0 
框架 提供 了 许多 的 协议 选项 和 替代 方法 ， 妨 碍 了 互 交 互 性 。OAuth 2.0 框架 的 灵活 性 也 对 
安全 产生 了 负面 影响 :由 于 可 选项 过 多 ， 不 安全 实现 的 可 能 性 也 增加 了 。 持 有 者 令 牌 ' 的 
缺点 (参见 第 15 章 ) 也 为 OAuth 2.0 招致 了 批评 。 


尽管 具有 这 些 问题 ，OAuth 2.0 框架 仍然 是 当前 Web API 安全 领域 的 一 个 重要 组 成 部 分 。 





注 1: 在 我 们 编写 本 章 时 ， 持 有 者 令 牌 是 唯一 完成 的 规范 ，MAC 规范 仍 未 完成 。 
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可 测试 性 





解决 问题 的 难处 在 于 问题 还 会 反弹 。 


作为 开发 者 ， 我 们 经 常 发 现 自己 花费 了 大 量 时间 ， 堂 试 解决 Web API 实现 中 可 能 发 生 的 问 
题 。 在 很 多 时 候 ， 我 们 使 用 浏览 器 或 者 HTTP 调试 程序 ， 用 试 错 方法 进行 测试 ， 但 是 这 种 
手工 测试 非常 耗费 时 间 ， 无 法 重复 ， 而 且 容易 出 错 。 雪 上 加 霜 的 是 ， 随 着 我 们 的 Web PIZ 
盖 的 使 用 场景 数量 增加 ， 手 工 测 试 每 个 可 能 的 执行 路 由 变 成 了 一 项 令 人 望 而 生 展 的 任务 。 


多 年 以 来 ， 业 内 出 现 了 各 种 工具 和 实践 ， 帮 助 开发 者 的 工作 。 例 如 : 自动 化 测试 领域 就 得 
到 了 许多 的 改进 。 我 们 在 这 里 所 说 的 自动 化 测试 ， 是 指 创建 或 配置 一 个 软件 ， 为 我 们 执行 
测试 。 采 用 自动 化 测试 具有 很 多 显而易见 的 优点 : 测试 可 重复 ， 我 们 可 以 在 任何 时 间 运 行 
测试 ， 甚 至 可 以 定时 自动 运行 测试 ， 无 需 进 行 任何 的 交互 。 

















在 本 章 中 ， 我 们 将 讨论 开发 者 对 ASP.NET Web API 进行 自动 化 测试 的 两 个 最 常见 的 选择 : 
单元 测试 和 集成 测试 。 对 于 不 熟悉 这 些 概念 的 读者 ， 我 们 简要 介绍 了 自动 化 测试 ， 还 提 到 
了 TDD (Test-Driven Development， 测 试 驱 动 开发 ) 这 一 核心 实践 。 自 动 化 测试 涉及 的 范 
围 很 广 ， 因 此 我 们 的 讨论 只 限于 ASP.NET Web API 的 测试 ， 以 及 如 何 使 用 这 一 技术 ， 测 
试 使 用 ASP.NET Web API 框架 构建 的 所 有 组 件 。 


17.1 单元 测试 

为 了 验证 其 他 某 些 代 码 单独 运行 时 的 预期 行为 ， 我 们 通常 会 编写 一 些 代 码 ， 这 些 代码 就 是 
单元 测试 。 编 写 单元 测试 时 ， 我 们 首先 将 应 用 程序 代码 分 为 离散 的 部 分 ， 如 类 的 方法 ， 这 
些 部 分 容易 管理 ， 可 以 单独 进行 测试 而 不 互相 影响 。 例 如 ， 对 于 ASP.NET Web API， 你 可 
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能 想 为 AptController 的 一 个 具体 实现 的 每 个 公共 方法 编写 一 个 单元 测试 。 单独 ”意味 着 
测试 之 间 没 有 依赖 关系 ， 因 此 测试 运行 的 顺序 不 应 该 影响 测试 的 最 终结 果 。 实 际 上 ， 你 应 
该 能 够 同时 运行 所 有 的 单元 测试 。 


一 个 单元 测试 通常 分 为 如 下 三 部 分 。 


Ok (arrange) : 将 一 个 或 多 个 对 象 设 置 为 已 知 的 状态 。 
(2) 操作 (act): 对 这 些 对 象 的 状态 进行 操作 ， 例 如 : 调用 对 象 的 方法 。 
(3) 断言 (assert) : 检查 测试 的 结果 ， 将 其 与 预期 结果 进行 比较 。 


和 源 代码 一 样 ， 我 们 也 应 该 将 单元 测试 作为 开发 的 生成 物 ， 将 其 保存 在 源 代码 库 中 。 将 测 
试 保 存在 代码 库 中 ， 你 就 可 以 将 测试 用 于 多 种 用 途 ， 例 如 ， 记 录 某 段 代码 的 预期 行为 ， 或 
者 在 实现 发 生变 化 时 确保 代码 行为 依然 正确 。 单 元 测试 应 该 容易 运行 ， 并 且 运 行 速 度 很 
快 。 否 则 ， 开 发 者 不 太 可 能 会 运行 这 些 测试 。 


















































17.1.1 使 用 测试 框架 

单元 测试 框架 强制 实现 某 些 测试 结构 ， 帮 助 我 们 简化 编写 单元 测试 的 过 程 ， 并 提供 运行 这 
些 测试 的 工具 。 和 任何 框架 一 样 ， 单 元 测试 框架 不 是 必须 的 ， 但 的 确 可 以 加 快 实现 和 运行 
单元 测试 的 过 程 。 


今天 ， 开 发 者 最 常用 的 单元 测试 框架 通常 是 xUnit 家 族 的 一 员 ， 其 中 有 : Visual Studio 单 
元 测试 工具 (Visual Studio 的 付费 版 本 中 提供 )， 或 开源 项 目 xUnit.NET。 本 章 ， 我 们 将 使 
用 xUnit.NET 进行 集成 测试 和 单元 测试 的 讨论 。xUnit 家 族 的 大 部 分 框架 要 么 是 JUnit 的 直 
接 移植 ， 要 么 是 借用 了 JUnit 的 一 些 概念 或 想法 ， 这 些 概念 和 想法 最 初出 现在 极限 编程 中 ， 
并 逐渐 流行 起 来 。 






































17.1.2 Visual Studio 单 元 测试 入 门 


为 了 使 开发 者 的 工作 更 容易 ，ASP.NET 团队 在 Visual Studio 中 ，ASP.NET Web API 应 用 
程序 的 New Project 对 话 框 中 ， 提 供 了 单元 测试 支持 (参见 图 17-1)。 

















通过 选中 Create Unit Test project 复 选 框 ， 你 就 告知 了 Visual Studio project lal, REH 
你 偏好 的 测试 框架 (默认 情况 下 ，Visual Studio 单元 测试 工具 是 唯一 可 用 的 框架 ) 创建 一 
个 新 的 单元 测试 项 目 。 当 你 选择 Visual Studio Unit Testing 时 ，Visual Studio 还 会 生成 一 个 
项 目 ， 其 中 包含 一 组 单元 测试 ， 测 试 默认 模板 中 的 ASP.NET Web API 控制 器 。 对 于 其 他 
的 测试 工具 ， 根 据 该 工具 在 Visual Studio 中 注册 的 项 目 模 板 定义 ，Visual Studio 的 行为 会 
发 生 改 变 。 
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Project Template 
Select a template: Description: 
c# # c# c# An ASP.NET Web API Project. 
51 5i 5i 


Empty Internet Intranet 
Application Application 





c 
5 
Mobile 
Application 




















Create a unit test project 
Test project name: 
MyTDDWebApi.Tests 

Test framework: 

Visual Studio Unit Test Additional Info 




















Ic Bess 














图 17-1: New Project 对 话 框 


对 于 ASP.NET Web API 项 目 模 板 ， 因 为 该 模板 包含 一 个 ValueController， 你 会 在 测 
试 项 目 中 找到 对 应 的 单元 测试 ValueControllerTest。 示 例 17-1 列 出 了 Visual Studio 在 
ValueControllerTest 中 生成 的 Get 方法 。 


示例 17-1: ASP.NET Web API 项目 模板 生成 的 单元 测试 


[TestClass] 
public class ValuesControllerTest 
{ 
[TestMethod] 
public void Get() 
{ 
// 准备 


ValuesController controller = new ValuesController(); // <1> 


// 操作 


IEnumerabLe<string> result = controller.Get(); // <2> 


// 断言 // <3> 
Assert. IsNotNull(result); 





Assert.AreEqual(2, result.Count()); 
Assert.AreEqual("value1", result.ELementAt(0)); 
Assert.AreEqual("value2", result.ELementAt(1)); 
} 

} 


你 可 以 看 到 ， 和 我 们 之 前 介绍 的 一 样 ， 这 个 方法 分 为 准备 、 操 作 和 断言 三 部 分 。 在 准备 部 
分 <1>， 待 测试 的 ValueController 进行 了 初始 化 ， 然 后 在 操作 部 分 <2> 调用 了 Get 方法 ， 
断言 部 分 <3> 对 预期 值 进行 了 断言 。 




















Assert 类 ， 以 及 这 个 单元 测试 中 用 到 的 TestClass 和 TestMethod 属性 ， 都 是 Visual Studio 
单元 测试 框架 的 一 部 分 。 在 Unit 家 族 的 任何 框架 中 ， 你 通常 都 能 找到 这 三 个 类 /属性 ， 
虽然 名 字 可 能 不 同 ， 但 功能 是 类 似 的 。 

















示例 17-1 展示 了 如 何 对 某 个 特定 的 控制 器 进行 单元 测试 ， 但 是 你 也 会 对 其 他 组 件 编写 单元 
测试 ， 例 如 : 封装 数据 访问 或 业务 逻辑 的 组 件 ， 以 及 Web API 中 才 有 的 组 件 (如 消息 处 理 
程序 ) 。 





17.1.3 xUnit.NET 


xUnit.NET 也 是 xUnit 家 族 中 的 一 员 ， 最 初 是 由 Brad Wilson 和 James Newkirk 提出 的 一 个 
开源 计划 。James Newkirk 也 是 JUnit 的 第 一 个 NET 平台 移植 ，NUnit 的 作者 之 一 。xUnit. 
NET 的 设计 目标 是 将 从 以 往 经 验 中 得 到 的 很 多 最 佳 实践 以 及 教训 ， 应 用 在 单元 测试 中 ， 更 
好 地 适应 .NET 平台 的 最 新 变化 。 例 如 : xUnitNET 框架 提供 的 在 测试 中 检验 异常 的 方法 ， 
比 其 他 传统 框架 的 做 法 更 为 优雅 。 虽 然 大 部 分 框架 使 用 属性 来 处 理 异常 检验 ， 但 是 xUnit. 
NET 使 用 了 委托 ， 如 示例 17-2 所 示 。 





























示例 17-2: 检查 预期 异常 的 单元 测试 
[TestClass] 
public class ValuesControllerTest 


[TestMethod] 
public void Get() 


{ 
// 准备 
ValuesController controller = new ValuesController(); 


// 断言 // <1> 
controller .Throws<HttpException>(() => controller.Get("bad")) // <2> 


} 
} 


你 可 以 看 到 ，Throws 方法 提供 一 个 简单 的 方式 ， 在 一 个 代码 行 中 表达 同时 表达 断言 <1> 和 
操作 <2>， 将 委托 传递 给 负责 抛 出 异常 的 方法 。 
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1. 单元 测试 的 组 织 

一 般 来 说 ， 一 个 单元 测试 应 该 只 测试 一 个 功能 或 行为 ， 否 则 很 难得 到 关于 具体 错误 的 真实 
反馈 。 此 外 ， 单 元 测试 自身 不 应 该 提供 任何 的 价值 ， 否 则 很 难 判断 预期 的 行为 应 该 是 什 
么 。 因 此 ， 单 元 测试 通常 是 以 提供 细 粒 度 反 馈 的 方法 组 织 的。 每 个 方法 应 该 只 展示 一 种 预 
期 的 行为 ， 但 是 可 能 会 用 到 一 个 或 多 个 断言 。 在 xUnitNET 中 ， 这 些 方法 必须 带 有 Fact 
属性 ， 以 标识 自己 为 单元 测试 。 你 可 能 还 想 使 用 不 同 的 标准 ， 将 单元 测试 组 织 为 群 组 ， 例 
如 : 测试 茶 个 组 件 的 单元 测试 ， 或 者 测试 菜 个 具体 用 例 的 单元 测试 。xUnit.NET 使 用 类 将 
所 有 的 测试 组 织 在 一 起 ， 形 成 单元 测试 术语 中 通常 所 说 的 测试 集 (test suite)。 



































2. Assert 类 

大 多 数 的 xUnit HEA, 包括 xUnit.net， 都 使 用 一 个 提供 常用 静态 方法 的 Assert 类 ,使 用 流 
接口 (fluent interface) 进行 比较 或 者 检验 ， 流 接口 可 以 更 明确 地 表达 操作 意图 。 例 如 ， 如 
果 要 验证 一 个 方法 调用 的 返回 值 应 该 不 为 nutL， 那 么 Assert.IsNotNull(result) 可 能 比 
Assert.IsTure(result == null) 更 能 表达 你 的 意图 。 但 这 只 是 编写 测试 的 开发 者 的 个 人 偏 
好 而 已 。 当 条 件 值 为 false 时 ，Assert 类 的 方法 都 会 抛 出 异常 ， 使 我 们 可 以 得 知 一 个 单元 
测试 是 否 失 败 了 。 


17.1.4 单元 测试 在 测试 驱动 开发 中 的 作用 

TDD (测试 驱动 开发 ) 是 一 种 设计 技术 ， 要 求 你 首先 编写 测试 ， 然 后 实现 所 需 的 应 用 程序 
代码 使 得 测试 通过 ， 从 而 以 单元 测试 驱动 产品 代码 的 设计 。 如 果 正 确 地 应 用 了 测试 驱动 开 
发 ， 你 得 到 的 生成 物 将 是 应 用 程序 代码 ， 以 及 描述 预期 行为 的 单元 测试 。 之 后 你 可 以 随时 
使 用 这 些 单元 测试 ， 确 保 产 品 代码 的 行为 依然 正确 。 但 是 ， 测 试 驱动 开发 不 仅 可 以 使 用 单 
元 测试 减少 产品 代码 中 的 缺陷 ， 而 且 可 以 改进 代码 的 设计 。 通 过 首先 编写 测试 ， 你 在 产品 
代码 实际 编写 之 前 就 描述 了 其 预期 行为 。 你 编写 的 是 你 需要 的 产品 代码 ， 没 有 机 会 编写 任 
何不 必需 要 的 实现 。 














pa 











人 们 常 犯 的 一 个 错误 是 ， 认 为 编写 一 些 单元 就 是 使 用 了 测试 驱动 开发 。 虽 然 测 试 驱 动 开 发 
要 求 使 用 单元 测试 驱动 代码 设计 ,但 是 编写 单元 测试 并 不 一 定 就 是 测试 驱动 开发 。 你 可 以 
在 编写 代码 之 后 编写 单元 测试 ， 这 通常 是 为 了 提高 测试 的 代码 覆盖 率 ， 但 是 这 并 不 意味 着 
你 使 用 了 测试 驱动 开发 ， 因 为 产品 代码 在 单元 测试 之 前 就 已 经 存在 了 。 


1. 红 绿 周期 

在 编写 单元 测试 时 ,“ 红 ”和 “ 绿 ” 可 以 分 别 用 于 替代 失败 和 成 功 。 大 多 数 的 测试 运行 器 
使 用 这 两 个 颜色 ， 帮 助 开发 者 快速 识别 哪些 测试 通过 或 失败 。 测 试 驱 动 开 发 也 大 量 使 用 这 
两 种 颜色 ， 了 驱动 新 功能 的 开发 。 因 为 你 测试 的 代码 还 不 存在 ， 所 以 首次 运行 测试 会 失败 。 
在 编写 测试 通过 所 需 的 代码 后 重新 运行 测试 ， 如 果 产 品 代 码 的 行为 正确 ， 你 将 会 得 到 一 个 
绿灯 ;如 果 产 品 代码 还 需 改 进 ， 你 将 会 得 到 一 个 红 灯 。 这 样 一 来 ， 你 会 不 断 地 经 过 红 / 绿 
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周期 。 但 是 ， 一 旦 一 个 测试 通过 ， 你 就 应 该 停止 编写 新 的 产品 代码 ， 直 到 测试 新 需求 的 新 
测试 失败 。 基 本 上 ， 你 编写 足够 的 应 用 程序 代码 使 测试 通过 ， 这 种 做 法 初 看 似乎 并 不 完 
美 ， 但 是 你 拥有 了 一 个 工具 ， 可 以 验证 对 产品 代码 的 任何 改进 都 不 会 影响 预期 的 行为 。 如 
有 果 你 想 对 产品 代码 的 某 些 方面 进行 改进 或 优化 ， 那 就 可 以 放手 去 做 ， 只 要 不 修改 组 件 的 公 
共 接 口 即 可 ， 还 可 以 使 用 原 有 的 测试 确保 底层 行为 依然 不 变 。 


2. 代码 重 构 

代码 重 构 是 指 修改 组 件 内 部 实现 而 保持 其 可 见 行为 不 变 的 操作 。 例 如 ， 将 一 个 大 型 的 公共 
方法 改 成 一 组 功能 单一 ， 更 易 维护 的 小 型 方法 。 在 重 构 产 品 代码 时 ， 你 不 能 修改 已 有 的 单 
元 测试 。 修 改 单元 测试 意味 着 增加 、 删 除 或 修改 已 有 的 功能 。 已 有 的 单元 测试 可 以 用 来 确 
保 ， 在 重 构 之 后 ， 应 用 程序 代码 的 可 见 行为 没有 改变 。 举 个 例子 ， 如 果 你 有 一 个 控制 器 操 
作 ， 返 回 客户 列表 ， 并 编写 了 验证 这 个 行为 的 单元 测试 。 不 管 获得 列表 的 内 部 实现 如 何 ， 
这 个 单元 测试 只 预期 得 到 同样 的 客户 列表 。 如 果 你 在 代码 中 发 现 了 一 些 问 题 ， 就 可 以 进行 
重 构 ， 改 进 代 码 ， 并 使 用 已 有 的 单元 测试 ， 确 保 新 加 入 的 修改 不 会 破坏 任何 功能 。 





























示例 17-3 展示 了 一 些 可 以 通过 内 部 重 构 进行 改进 的 代码 。 


示例 17-3: 两 个 实例 化 HttpCLient 的 方法 
public abstract class IssueSource : IIssueSource 


{ 
HttpMessageHandler _handler = null; 


protected IssueSource(HttpMessageHandler handler = null) 


{ 


_handler = handler; 


} 


public virtual Task<IEnumerable<Issue>> FindAsync() 


{ 


HttpClient client; 
if (_handler != null) 

client = new HttpClient(_handler); 
else 

client = new HttpClient(); 


// 使 用 HttpCLient 实例 …… 


public virtual Task<IEnumerable<Issue>> FindAsyncQuery(dynamic values) 
HttpClient client; 
if (_handler != null) 
client = new HttpClient(_handler); 
else 


client = new HttpClient(); 


// 使 用 HttpClient 实例 …… 
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} 
} 


这 两 个 方法 都 创建 了 一 个 新 的 HttpClient 实例 。 如 果实 例 化 代码 需要 进行 修改 ， 如 添加 新 
的 设置 ， 那 么 这 两 个 方法 都 需要 修改 。 为 此 ， 我 们 可 以 将 实例 化 代码 移 到 一 个 通用 的 内 部 
方法 中 (参见 示例 17-4)。 


示例 17-4: HttpClient 实例 化 代码 移 到 通用 方法 中 


public abstract class IssueSource : IIssueSource 
HttpMessageHandler _handler = null; 


protected IssueSource(HttpMessageHandler handler = null) 


{ 


_handler = handler; 


} 
public virtual Task<IEnumerable<Issue>> FindAsync() 


HttpClient client = GetClient(); 


// 使 用 HttpClient 实例 ……: 


public virtual Task<IEnumerable<Issue>> FindAsyncQuery(dynamic values) 


{ 
HttpClient client = GetClient(); 


// 使 用 HttpClient 实例 …… 


protected HttpClient GetClient() 
{ 


HttpClient client; 


if (_handler != null) 

client = new HttpClient(_handler); 
else 

client = new HttpClient(); 


return client; 
} 
} 


我 们 移 除 了 重复 代码 ， 但 没有 修改 这 个 类 的 外 部 接口 。 预 期 的 行为 保持 不 变 ， 因 此 单元 测 
试 也 无 需 修改 ， 可 以 用 于 验证 我 们 的 改动 没有 破坏 任何 功能 。 


3. 依赖 注入 和 模拟 

在 静态 语言 的 单元 测试 中 ， 因 为 依赖 项 无 法 在 运行 时 很 容易 地 替换 ， 所 以 经 常会 使 用 依赖 注 
入 。 单 元 测试 关注 的 是 测试 特定 代码 在 隔离 环境 中 的 行为 ， 因 此 需要 尽量 减少 任何 外 部 依赖 
项 在 测试 时 的 影响 。 使 用 依赖 注入 ， 你 可 以 对 所 有 硬 编码 的 依赖 项 进行 替换 ， 在 运行 时 注入 
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依赖 ， 以 伪造 依赖 项 的 行为 。 例 如 ， 如 果 一 个 Web API 控制 器 依赖 一 个 数据 访问 类 进行 

据 库 查 询 ， 那 么 我 们 不 希望 对 带 有 这 一 明确 依赖 的 控制 器 进行 单元 测试 ， 因 为 每 次 测试 运行 
时 都 需要 初始 化 和 准备 好 数据 库 。 我 们 首先 需要 利用 接口 或 抽象 类 ， 把 控制 器 和 实际 访问 数 
据 库 的 类 实现 分 开 ， 然 后 通过 构造 函数 参数 或 者 属性 设置 方法 ， 将 其 注入 控制 器 。 剩 下 的 任 
务 就 是 由 单元 测试 创建 一 个 伪造 的 类 ， 这 个 类 实现 之 前 用 到 的 接口 或 抽象 类 ， 同 时 满足 测试 
的 需求 。 这 个 伪造 的 类 可 以 简单 地 模拟 相同 的 接口 ， 使 用 在 这 个 测试 中 预先 初始 化 的 内 存 列 
表 ， 为 测试 返回 预期 的 值 。 使 用 这 种 方法 ,我们 可 以 去 除 测 试 中 的 数据 库 依 赖 。 我 们 可 以 使 
用 多 个 开源 框架 ,例如 Moq 或 RhinoMocks， 从 一 个 接口 或 基 类 自动 生成 伪造 的 或 模拟 的 类 ， 
并 设置 这 个 模拟 类 的 预期 行为 。 示 例 17-5 是 我 们 的 问题 跟踪 Web API 的 一 段 单元 测试 ， 测 
试 中 实例 化 了 一 个 模拟 类 (由 Mog 框架 生成 )， 以 模仿 数据 访问 类 的 行为 。 


示例 17-5: 使 用 模拟 类 的 单元 测试 
public class IssuesControllerTests 


{ 
private Mock<IIssueSource> _mockIssueSource = new Mock<IIssueSource>(); // <1> 
private IssuesController _controller; 


























public IssuesControllerTests() 


{ 


_controller = new IssuesControLLer(_mockIssueSource.0bject); // <2> 


} 


[Fact] 
public void ShouldCallFindAsyncWhenGETForAllIssues() { 
_controller.Get(); 
_mockIssueSource.Verify(i=>i.FindAsync()); // <3> 
} 
} 


示例 代码 使 用 Mog 框架 提供 的 Mock 类 ， 实 例 化 了 IIssuesource 接口 的 一 个 模拟 类 <1>， 并 把 
这 个 实例 注入 IssuesController 构造 国 数 <2>。 这 个 单元 测 调用 了 控制 器 的 Get 方法 ， 并 验证 
Mock 对 象 的 FindAsync 方法 实际 得 到 了 调用 <3>。Verify 方法 也 是 由 Mog 框架 提供 的 ， 用 于 检 
验 一 个 方法 是 否 得 到 调用 ， 以 及 调用 次 数 ( 例 如， 调用 FindAsyne 方法 超过 一 次 就 说 明代 码 存 
在 缺陷 )。 如 果 我 们 没有 使 用 Mog 框架 ， 那 么 要 实现 类 似 的 功能 就 需要 手工 编写 重复 的 代码 。 























17.2 ”对 ASP.NET Web API 实 现 进行 单元 测试 


ASP.NET Web API 实现 中 有 一 些 组 件 需要 隔离 测试 。 在 本 章 中 ， 我 们 将 介绍 其 中 儿 个 ， 例 
Ail; ApiController, MediaTypeFormatter 和 HttpMessageHandLer。 在 本 章 最 后 ， 我 们 还 会 
探讨 如 何 使 用 HttpClient 类 和 内 存 托管 进行 集成 测试 。 


17.2.1 测试 ApiController 


在 ASP.NET Web API 中 ，ApiController 是 你 的 Web API 实现 的 入 口 ， 作 为 一 个 桥梁 ， 通 
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过 HTTP 癌 外 界 提供 应 用 系统 的 逻辑 。ApiController 时 


需要 测试 的 主要 的 一 点 是 ， 在 隔离 


环境 下 ， 测 试 控制 器 如 何 对 不 同 的 请 求 消 息 做 出 反应 。 你 可 以 根据 Web API 支持 的 场景 或 


用 例 ， 选 





择 使 用 哪 种 消息 。 隔 离 也 是 单元 测试 的 关键 因素 ， 因 为 你 无 法 假定 在 测试 运行 之 


前 ，Web API 运行 时 中 的 各 种 条 件 都 正确 进行 了 设置 。 例 如 ， 如 果 你 的 pages! 依 


赖 通过 身份 验证 的 用 户 执行 某 种 操作 ， 那 么 就 必须 在 单元 测试 中 对 用 户 进 





息 的 初始 化 也 是 如 此 。 


行 配置 。 请 求 消 


在 这 一 节 中 ， 我 们 将 使 用 之 前 构建 的 管理 问题 的 Apicontroller 作为 起 点 ， 尝 试 为 这 个 控 
制 器 编写 单元 测试 ， 和 覆盖 支 持 的 一 些 用 例 。 让 我 们 从 示例 17-6 开始 。 





示例 17-6: 我 们 的 IssuesController 实现 


public class IssuesController : ApiController 


{ 


} 


示例 17-6 是 IssuesController 的 最 初 实现 ， 初 看 起 来 六 


private readonly IIssueSource _issueSource; 


public IssuesController(IIssueSource issueSource ) 
{ 


_issueSource = issueSource; 


} 
public async Task<Issue> Get(string id) // <1> 
{ 
var issue = await _issueSource.FindAsync(id); 
if(issue == null) 


throw new HttpResponseException(HttpStatusCode.NotFound) ; 
return issue; 


} 


public async Task<HttpResponseMessage> Post(Issue issue) // <2> 
{ 
var createdIssue = await _issueSource.CreateAsync(issue) ; 
var link = Url.Link("DefaultApi", new {Controller = "issues", 
id = createdIssue.Id}); 


var response = Request.CreateResponse(HttpStatusCode.Created, createdIssue); 


response.Headers.Location = new Uri(link); 
return response; 


} 





EAN 4 2%, IssuesController 包含 





一 个 Get 方法 ， 用 于 获取 存在 的 问题 <1>， 以 及 一 个 Post 方 法， 用 于 添加 新 问题 <2>。 


IssuesController 还 依赖 一 个 IIssueSource 实例 进行 持久 性 问题 的 处 型 


1. 测试 


我 们 的 第 一 


IIssueSource 实现 ， 返 




















o 


laz 


Get 方 法 

















个 Get 方 法 (参见 示例 17-6) 看 起 来 非常 简单 ， 这 个 方法 将 调用 委托 给 
加 一 个 已 经 存在 的 问题 。 单 元 测试 不 应 该 依赖 IIssueSource 的 具体 





实现 ， 因 此 我 们 会 使 用 一 个 Mock。 
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示例 17-7: Get 方法 的 第 一 个 单元 测试 
public class IssuesControllerTests 


{ 
private Mock<IIssueSource> _mockIssueSource = new Mock<IIssueSource>(); 
private IssuesController _controller; 


public IssuesControllerTests() 


{ 
_controller = new IssuesController(_mockIssueSource.Object); // <1> 
} 
[Fact] 
public void ShouldReturnIssueWhenGETForExistingIssue( ) 
{ 


var issue = new Issue(); 


_mockIssueSource.Setup(i => i.FindAsync('"1")) 
.Returns(Task.FromResult(issue)); // <2> 


var foundIssue = _controller.Get("1").Result; // <3> 


Assert.Equal(issue, foundIssue); // <4> 
} 
} 


示例 17-7 主要 验证 的 是 ， 控 制 器 调用 TIssueSource 实例 的 FindAsync 方法 ， 返 回 一 个 存在 
的 问题 。 在 测试 初始 化 部 分 ， 代 码 首先 使 用 IIssueSource 的 一 个 模拟 实例 ， 初 始 化 控制 器 
<1>， 并 对 这 个 模拟 实例 进行 设置 ， 使 其 收 到 参数 “1“ 时 返回 一 个 问题 <2>， 这 个 参数 与 
传递 给 控制 器 的 Get 方法 的 参数 相同 <3>。 最 后 ， 探 制 器 返回 的 问题 与 模拟 实例 中 注入 的 
问题 相 比 较 ， 验 证 二 者 相同 <4>。 





这 是 当 IIssueSource 实现 返回 一 个 问题 时 的 情况 ， 但 是 我 们 也 希望 测试 当 所 请 求 的 问题 没 找 
到 时 ， 控 制 器 如 何 做 出 反应 。 我 们 将 创建 一 个 新 的 测试 ， 验 证 这 一 场景 (参见 示例 17-8)。 














示例 17-8: 覆盖 问题 不 存在 情况 的 单元 测试 
[Fact] 
public void ShouldReturnNotFoundWhenGETForNonExistingIssue() 
{ 


_mockIssueSource.Setup(i => i.FindAsync("1")) 
.Returns(Task.FromResult((Issue)null)); // <1> 


var ex = Assert. Throws<AggregateException>(() => 


{ 
var task = _controller.Get("1"); 
var result = task.Result; 

H; // <2> 


Assert. IsType<HttpResponseException>(ex.InnerException); // <3> 
Assert. Equal(HttpStatusCode.NotFound, 
((HttpResponseException) ex.InnerException).Response.StatusCode); // <4> 
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当 所 请 求 的 问题 不 存在 时 ， 控 制 器 会 抛 出 一 个 状态 码 为 494 的 HttpException。 单 元 测试 对 
Mock 进行 初始 化 ， 使 其 在 问题 ID 为 1 时 返回 一 个 结果 为 null 的 Task。 在 单元 测试 的 断言 
部 分 ， 我 们 使 用 Assert 类 的 Throws 方法 (由 xUnit.NET 提供 ) ， 检 验方 法 是 否 返 回 一 个 异 
常 <2>。 这 个 Throws 方法 使 用 一 个 可 能 抛 出 异常 的 委托 为 参数 ， 并 尝试 捕获 这 个 异常 。 最 
后 ， 我 们 验证 抛 出 的 异常 类 型 是 否 为 HttpResponseException <3>， 异 常 的 状态 码 是 否 为 
404 <4>。 





























2. 测试 Post 方 法 

控制 器 中 的 Post 方法 创建 一 个 新 间 题 。 我 们 需要 验证 这 个 问题 正确 传递 给 了 IIssueSsource 
实现 ， 并 且 响 应 在 离开 控制 前 之 前 正确 设置 了 标 头 。 这 个 控制 器 模型 控制 器 上 下 文中 的 依 
fii HttpRequestMessage 和 UrlHelper， 生 成 响应 和 指向 新 资源 的 链接 ， 因 此 我 们 需要 进行 
一 些 枯燥 的 工作 ， 初 始 化 运行 时 配置 和 路 由 表 (参见 示例 17-9)。 





示例 17-9: 初始 化 运行 时 配置 和 路 由 表 


_controller.Configuration = new HttpConfiguration(); // <1> 


var route = _controller.Configuration.Routes.MapHttpRoute( 
name: "DefaultApi", 
routeTemplate: "api/{controller}/{id}", 
defaults: new { id = RouteParameter.Optional } 


); // <2> 


var routeData = new HttpRouteData(route, 
new HttpRouteValueDictionary 
{ 
{ "controller", "Issues" } 
} 
)3 


_controller.Request = new HttpRequestMessage(HttpMethod.Post, 

"http: //test.com/issues"); // <3> 
_controller.Request.Properties.Add(HttpPropertyKeys.HttpConfigurationKey, 
controller.Configuration) ; 
_controLler.Request.Properties.Add(HttpPropertyKeys.HttpRouteDataKey, 

routeData); // <4> 





这 段 代 码 中 在 控制 器 实例 中 设置 了 一 个 新 初始 化 的 HttpConfiguration MR <I>, 设置 了 
一 个 路 由 <2> 并 添加 到 已 有 的 配置 对 象 中 ， 并 创建 了 一 个 新 的 请 求 对 象 ， 为 其 设置 HTTP 
动词 和 测试 预期 的 URI <3>。 最 后 ， 代 码 通过 通用 属性 Properties， 将 路 由 数据 和 配置 对 
象 关联 到 请 求 对 象 ，UrtHelper 会 使 用 Properites 查找 这 些 对 象 <4>。 








我 们 在 下 一 节 中 将 看 到 ，ASP.NET Web API 团队 已 经 在 Web API 中 简化 了 这 一 场景 。 同 
时 ， 如 果 你 仍然 在 使 用 Web API 的 第 一 个 版 本 ，WebApiContrib MEA (参见 http://www. 
nuget.org/packages/WebApiContrib.Testing) 也 提供 一 组 扩展 方法 ， 可 以 用 一 行 代码 完成 对 
控制 器 的 配置 (参见 示例 17-10)。 
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示例 7-10: 用 于 在 测试 中 配置 Apicontroller 的 扩展 方法 
public static class ApiControllerExtensions 
{ 
public static void ConfigureForTesting(this ApiController controller, 
HttpRequestMessage request, 
string routeName = null, 
IHttpRoute route = null); 


public static void ConfigureForTesting(this ApiController controller, 
HttpMethod method, 
string uri, 
string routeName = null, 
IHttpRoute route = null); 


} 


这 些 扩展 方法 的 参数 包括 要 使 用 的 请 求实 例 或 者 HITP 方法 ， 还 可 以 传人 在 测试 中 使 用 的 
URL 或 默认 路 由 。 我 们 将 在 本 章 中 使 用 这 些 扩展 方法 ， 以 简化 测试 代码 。 示 例 17-11 列 出 
了 我 们 的 第 一 个 单元 测试 。 


示例 17-11: 第 一 个 测试 ， 验 证 调用 CreateAsync 


[Fact] 
public void ShouldCallCreateAsyncWhenPOSTForNewIssue() 
{ 
// 准备 
_controller.ConfigureForTesting(HttpMethod.Post, "http://test.com/issues"); // <1> 
var issue = new Issue(); 
_mockIssueSource.Setup(i => i.CreateAsync(issue) ) 
.Returns(() => Task.FromResult(issue)); // <2> 

















// 操作 


var response = _controller.Post(issue).Result; // <3> 


// 断言 
_mockIssueSource.Verify(i=>i 
.CreateAsync(It.Is<Issue>(iss => iss.Equals(issue)))); // <4> 


} 
测试 使 用 扩展 方法 ConfigureForTesting, Xf IssuesController 中 的 HttpRequestMessage 和 
UrlHelper 进行 实例 化 <1>。 控 制 器 初始 化 完成 之 后 ， 测 试 将 IIssuesource 模拟 实例 设置 
为 返回 一 个 异步 任务 ， 模 拟 后 台 的 持久 化 操作 <2>， 并 使 用 一 个 新 问题 调用 控制 器 的 Post 
方法 <3>。 测 试验 证 模拟 实例 的 CreateAsync 方法 确实 得 到 了 调用 <4>。 








我 们 还 需要 一 个 测试 ， 验 证 调用 IIssueSource 实现 的 CreateAsync 方法 后 ， 返 回 了 一 个 有 
效 的 响应 。 有 具体 实现 请 见 示例 17-12. 





示例 17-12: 第 二 个 测试 ， 验 证 响应 消息 
[Fact] 
public void ShouldSetResponseHeadersWhenPOSTForNewIssue() 


{ 
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// 准备 

_controller.ConfigureForTesting(HttpMethod.Post, "http://test.com/issues"); 
var createdIssue = new Issue(); 

createdIssue.Id = "1"; 

_mockIssueSource.Setup(i => i.CreateAsync(createdIssue)).Returns(() => 
Task.FromResult(createdIssue)); // <1> 














// 操作 


var response = _controller.Post(createdIssue).Result; // <2> 


// 断言 
response. StatusCode. ShouldEqual(HttpStatusCode.Created); // <3> 
response.Headers.Location.AbsoluteUri.ShouldEqual("http://test.com/issues/1"); 


} 


个 测试 对 IIssueSource 模拟 对 象 进 行 设置 ， 使 其 返回 结果 为 已 创建 问题 的 任务 <1>， 这 
ne bees 给 控制 器 示例 的 Post 方法 <2>。 测 试验 证 返回 的 HTTP 状态 码 等 于 
Created <3>， 而 且 新 资产 的 地 址 为 http://test.com/issues/1。 到 这 里 ， 你 应 该 对 ASP. 


NET Web API 中 控制 右 的 单元 测试 有 了 一 定 的 了 解 。 在 接 下 来 的 小 节 中 ， 我 们 将 讨论 如 何 
测试 MediaTypeFormatter 和 HttpMessageHandler , 




















3. Web API 2 中 的 IHttpActionResult 

Web API2 中 引入 了 一 个 新 接口 IHttpActionResult (等同 于 ASPNET MVC 中 的 
ActionResutt) ， 极 大 简化 了 对 控制 器 的 单元 测试 。 现 在 ， 一 个 控制 器 方法 可 以 返回 IHttp 
ActionResult 的 一 个 实现 ， 其 内 部 使 用 Request 或 UrlHelper 生成 链接 ， 因 此 单元 测试 可 
以 只 关注 返回 的 THttpActionResult 实例 。 下 面 的 代码 展示 了 使 用 IHttpActionResult 实例 
的 Post 方法 : 




















public async Task<IHttpActionResult> Post(Issue issue) 
{ 
var createdIssue = await _issueSource.CreateAsync(issue); 
var result = new CreatedAtRouteNegotiatedContentResult<Issue>( 
"DefaultApi", 
new Dictionary<string, object> { { "id", createdIssue.Id } }, 
createdIssue, 
this); 


return result; 


} 





CreatedAtRouteNegotiatedContentResult 也 是 由 框架 提供 的 一 个 实现 ， 创 建 了 一 个 新 资源 ， 
设置 响应 消息 中 的 资源 地 址 。 单 元 测试 也 得 到 了 很 大 的 简化 ， 如 示例 17-13 所 示 。 


示例 17-13: 第 二 个 测试 ， 验 证 响应 消息 


[Fact] 
public void ShouLdSsetResponseHeadersNhenPOSTForNewIssue() 


// 准备 

















var createdIssue = new Issue(); 
createdIssue.Id = "1"; 

_mockIssueSource.Setup(i => i.CreateAsync(createdIssue)).Returns(() => 
Task. FromResult(createdIssue) ); 


// 操作 
var result = _controller.Post(createdIssue).Result as 
CreatedAtRouteNegotiatedContentResult; // <1> 


// 断言 
resuLt.ShouldNotBeNull(); // <2> 
result.Content.ShouldBeType<Issue>(); // <3> 


} 


这 个 单元 测试 只 是 返 








回 的 结果 转换 为 预期 的 类 型 (在 这 个 测试 中 是 CreatedAtRouteNegotia 


tedContentResult) <1>， 并 验证 结果 不 为 null <2>， 而 且 结 果 中 的 内 容 为 Issue 类 型 的 一 
个 实例 <3>。 这 个 测试 不 再 需要 之 前 使 用 的 初始 化 代码 ， 因 为 现在 所 有 的 内 容 协 商 和 链接 




















| 
管理 逻辑 都 封装 在 IHttpActionResult 实现 之 中 ， 和 这 个 单元 测试 无 关 。 


17.2.2 ”测试 MediaTypeFormm 
作为 处 理 新 媒体 类 型 或 内 容 协商 的 主要 部 分 ，MediaTypeFormatter 的 实现 有 几 个 方面 需要 





在 单元 闹 





I 试 中 解决 。 这 些 方面 有 : 正确 处 型 











ater 

















所 支持 的 媒体 类 型 ， 将 模型 从 指定 媒体 类 型 进 


行 转换 或 者 转换 到 指定 媒体 类 型 ， 或 者 在 需要 时 检查 某 些 设置 的 正确 配置 ， 例 如 : 编码 或 


者 映射 。 








从 示例 17-14 中 的 MediaTypeFormatter 类 定义 ， 你 可 以 对 甚 单元 测试 得 到 一 个 粗略 的 概念 。 


示例 17-14: MediaTypeFormatter 类 定义 


public abstract class MediaTypeFormatter 


{ 


public 


public 


public Collection<MediaTypeMapping> 





Collection<Encoding> SupportedEncodings { get; } 


Collection<MediaTypeHeaderValue> SupportedMediaTypes { get; } 


MediaTypeMappings { get; } 


public abstract bool CanReadType(Type type); 


public 


public 


abstract bool CanWriteType(Type type); 


virtual Task<object> ReadFromStreamAsync(Type type, Stream readStream, 


HttpContent content, IFormatterLogger formatterLogger ); 


public virtual Task WriteToStreamAsync(Type type, object value, 
Stream writeStream, HttpContent content, TransportContext transportContext) ; 


} 


使 用 不 同 的 单元 测试 ， 我 们 可 以 进行 以 下 检验 。 





可 测试 性 | 393 


。 所 支持 的 媒体 类 型 (参见 示例 17-15) 在 SupportedMediaType 集合 中 进行 了 正确 配置 。 
对 于 我 们 在 第 13 章 中 构建 的 支持 联合 媒体 类 型 (如 Atom 或 RSS) 的 格式 化 程序 ， 这 
个 测试 意味 着 对 于 所 支持 的 这 些 媒 体 类 型 ， 集 合 中 分 别 包含 application/atomxml 和 


application/rss+xml, 


示例 17-15: 检查 所 支持 媒体 类 型 的 单元 测试 
[Fact] 
public void ShouldSupportAtom() 
{ 


var formatter = new SyndicationMediaTypeFormatter(); 


Assert. True(formatter .SupportedMediaTypes 
.Any(s => s.MediaType == "application/atom+xml")); 


} 


[Fact] 
public void ShouldSupportRss() 
{ 


var formatter = new SyndicationMediaTypeFormatter(); 


Assert. True(formatter .SupportedMediaTypes 
.Any(s => s.MediaType == "application/rss+xmLl")); 


} 








。 在 CanReadType 和 CanWriteType 方法 中 ， 支 持 给 定 模型 类 型 的 序列 化 或 反 序 列 化 (参见 
示例 17-16)。 


示例 17-16: 检查 实现 是 否 能 够 读 或 写 一 个 类 型 的 单元 测试 
[Fact] 
public void ShouldNotReadAnyType() 
{ 


var formatter = new SyndicationMediaTypeFormatter(); 
var canRead = formatter.CanReadType(typeof(object)); 


Assert.False(canRead); 


} 


[Fact] 
public void ShouldWriteAnyType() 
{ 


var formatter = new SyndicationMediaTypeFormatter(); 


var canWrite = formatter.CanWriteType( typeof (object) ) ; 


Assert. True(canWrite); 


} 


。 使 用 所 支持 的 媒体 类 型 ， 从 流 读 取 模 型 / 向 流 写 入 模型 的 代码 正常 工作 (参见 示例 17-17)。 
这 需要 分 别 测试 WriteToStreamAsync 和 ReadFromStreamAsync 方法 。 





示例 17-17: 验证 WriteToStreamAsync 方法 行为 的 单元 测试 


[Fact] 
public void ShouldSerializeAsAtom( ) 


{ 


var ms = new MemoryStream(); 


var content = new FakeContent(); 
content.Headers.ContentType = new MediaTypeHeaderVaLlue("application/atom+xmL") ; 


var formatter = new SyndicationMediaTypeFormatter(); 

var task = formatter .WriteToStreamAsync(typeof(List<ItemToSerialize>), 
new List<ItemToSerialize> { new ItemToSerialize { ItemName = "Test" }}, 
ms, 
content, 


new FakeTransport() 


); 
task.Wait(); 
ms.Seek(0, SeekOrigin.Begin); 


var atomFormatter = new Atom10FeedFormatter(); 
atomFormatter .ReadFrom(XmlReader.Create(ms)); 


Assert.Equal(1, atomFormatter.Feed.Items.Count()); 


} 
public class ItemToSerialize 
{ 
public string ItemName { get; set; } 
} 
public class FakeContent : HttpContent 
{ 
public FakeContent() 
: base() 
{ 
} 
protected override Task SerializeToStreamAsync(Stream stream, TransportContext 
context) 
{ 
throw new NotImplementedException(); 
} 
protected override bool TryComputeLength(out long length) 
{ 
throw new NotImplementedException(); 
} 


} 


public class FakeTransport : TransportContext 


{ 
public override ChannelBinding GetChannelBinding(ChannelBindingKind kind) 
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{ 


throw new NotImplementedException(); 


} 
} 
示例 17-17 中 的 单元 测试 序 iil in ItemToSerialize 类 型 的 条 目 ， 这 组 条 目 在 测试 
中 也 定义 为 一 个 Atom 源 。 这 个 测试 主要 验证 了 ， 当 ZAAI A) application/atom+xml 
Ik}, SyndicationMediaTypeFormatter 能 够 序列 化 这 组 条 目 。WriteToStreamAsync 方法 需要 
HttpContent 和 TransportContext 实例 ， | ( 标 头 除 
外 )， 因 此 测试 定义 了 两 个 不 包含 任何 特殊 逻辑 的 伪造 类 。 测 试 还 使 用 WCF 的 联合 类 ， 将 
流 反 序列 化 为 一 个 Atom 源 ， 以 确保 序列 化 操作 正确 完成 。 


。 所 有 需要 的 设置 都 正确 进行 了 初始 化 。 例 如 ， 如 果 你 要 求 在 查询 字符 串 中 支持 媒体 类 型 
那么 单元 测试 可 以 检查 这 个 映射 是 否 在 MediaTypeMappings 集合 中 正确 进行 了 配 
置 。 示 例 17-18 对 此 进行 了 演示 。 


示例 17-18: 检查 所 支持 媒体 类 型 映射 的 单元 测试 
[Fact] 
public void ShouldMapAtomFormatInQueryString() 
{ 


var formatter = new SyndicationMediaTypeFormatter(); 


























Assert. True(formatter .MediaTypeMappings .OfType<QueryStringMapping>() 


.Any(m => m.QueryStringParameterName == "format" && 
m.QueryStringParameterValue == "atom" && 
m.MediaType.MediaType == "application/atom+xmL")); 


} 


示例 17-18 中 的 测试 检查 是 否 为 查询 字符 串 参 数 定义 了 一 个 MediaTypeMapping， 将 值 为 
atom 的 查询 字符 串 变 量 format 映射 到 媒体 类 型 application/atom+xml。 


17.2.3 单元 测试 HttpMessageHandler 
HttpMessageHandler 是 Web API 运行 时 管道 的 通用 拦截 机 制 。 消 息 处 理 程序 是 异步 的 ， 通 
常 只 包含 一 个 方法 SendAsync， 用 于 处 理 请 求 消息 (HttpRequestMessage)， 并 返回 一 
Task 实例 ， 代 表 获 取 一 个 响应 (HttpResponseMessage) 的 任务 (参见 示例 17-19)。 








示例 17-19: HttpMessageHandler 类 定义 
public abstract class HttpMessageHandler 


{ 


protected internal abstract Task<HttpResponseMessage> SendAsync( 
HttpRequestMessage request, CancellationToken cancellationToken); 





SendAsync 方法 不 是 公开 的 ， 因 此 无 法 在 单元 测试 中 直接 调用 ,但 是 框架 提供 了 一 个 
System.Net.Http.MessageInvoker 类 ， 可 以 用 于 调用 SendAsync 方法 。System.Net.Http . 
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MessageInvoker 类 的 构造 国 数 参 数 是 一 个 HttpMessageHandler 实例 ， 并 提供 一 个 公共 方法 
SendAsync， 用 于 调用 这 个 处 理 程 序 上 的 同名 方法 。 示 例 17-20 简单 展示 了 如 何 对 一 个 Http 
MessageHandler 示例 的 SendAsync 方法 进行 单元 测试 。 但 是 ，HttpMessageHandler 可 能 使 
用 外 部 依赖 或 者 包含 一 些 其 他 的 公共 方法 ， 你 也 需要 对 其 进行 测试 。 








示例 17-20: 对 HttpMessageHandler 进行 单元 测试 


[Fact] 
public void ShouldInvokeHandler() 
{ 


var handler = new SampleHttpMessageHandler(); 


var invoker = new HttpMessageInvoker (handler); 
var task = invoker.SendAsync(new HttpRequestMessage(), new CancellationToken()); 
task.Wait(); 


var response = task.Result; 


// 对 响应 进行 断言 
I aen 
} 


17.2.4 ”测试 ActionFilterAttribute 

操作 筛选 器 和 HTTP 消息 处 理 程序 一 样 都 是 消息 拦截 机 制 ， 但 是 在 操作 上 下 文 初始 化 
之 后 ， 操 作 即 将 执行 之 前 在 运行 时 管道 中 运行 得 更 深入 。 操 作 和 筛选 器 的 基 类 System. 
Web.Http.Filters.ActionFilterAttribute (参见 示例 17-21) 提供 两 个 可 以 重 写 的 方法 : 
OnActionExecuting 和 OnActionExcuted， 可 以 在 操作 执行 前 后 拦截 调用 。 

















示例 17-21: ActionFilterAttribute 类 定义 


public abstract class ActionFilterAttribute : FilterAttribute, 
IActionFilter, 
IFilter 


public virtual void OnActionExecuted(HttpActionExecutedContext 
actionExecutedContext); 


public virtual void OnActionExecuting(HttpActionContext 
actionContext); 


} 


这 两 个 方法 都 是 公开 的 ， 因 此 可 以 直接 在 单元 测试 中 调用 。 示 例 17-22 是 一 个 非常 基础 的 
过 滤器 实现 ， 使 用 应 用 程序 码 对 客户 端 进行 身份 验证 。 我 们 将 使 用 这 个 具体 实现 ， 来 展示 
如 何 对 不 同 的 场景 进行 单元 测试 。 


示例 17-22: 使 用 应 用 程序 码 对 客户 端 进行 身份 验证 的 操作 筛选 器 
public interface IKeyVerifier 


{ 
bool VerifyKey(string key); 
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} 


public class ApplicationKeyActionFilter : ActionFilterAttribute 


public const string KeyHeaderName = "X-AuthKey"; 
IKeyVerifier keyVerifier; 


public ApplicationKeyActionFilter() 
{ 
} 


public ApplicationKeyActionFilter(IKeyVerifier keyVerifier) // <1> 
{ 


this.keyVerifier = keyVerifier; 


} 


public Type KeyVerifierType // <2> 


public override void OnActionExecuting(HttpActionContext 
actionContext) 
{ 
if (this.keyVerifier == null) 
{ 
if (this.KeyVerifierType == null) 
{ 


throw new Exception("The keyVerifierType was not provided"); 


} 


this.keyVerifier = (IKeyVerifier )Activator 
.CreateInstance(this.KeyVerifierType) ; 


} 


IEnumerable<string> values = null; 


if (actionContext.Request.Headers 
. TryGetVaLlues(KeyHeaderName, out values)) // <3> 


{ 

var key = values.First(); 

if (!this.keyVerifier.VerifyKey(key)) // <4> 

{ 

actionContext.Response = 
new HttpResponseMessage(HttpStatusCode.Unauthorized) ; 

} 
} 
else 
{ 

actionContext.Response = 

new HttpResponseMessage(HttpStatusCode.Unauthorized) ; 

} 





base.OnActionExecuting(actionContext); 
} 
} 


示例 中 的 这 个 操作 算 选 器 的 构造 函数 参数 为 一 个 IKeyverifier 实例 ， 用 于 验证 一 个 码 值 是 
否 有 效 <1>。 操 作 筛 选 器 也 可 以 用 做 属性 ， 因 此 这 个 实现 提供 一 个 属性 KeyVerifierType 
<2>， 在 筛选 器 用 做 属性 时 设置 IKeyvVerifier。 这 个 筛选 器 只 实现 了 OnActionExecuting Fy 
法 ， 这 个 方法 在 操作 执行 之 前 运行 。 这 个 筛选 器 检查 上 下 文中 设置 的 请 求 消息 的 X-Auth 标 
头 <3>， 并 尝试 将 这 个 标 头 值 传 给 IKeyVerifier 实例 进行 验证 <4>。 如 果 这 个 码 值 无 法 得 
到 验证 或 者 没有 在 请 求 消息 中 找到 ， 那 么 这 个 秘 选 器 会 在 当前 上 下 文中 设置 一 个 HTTP 状 
态 码 为 401 的 响应 消息 ， 管 道 执行 因此 中 断 。 


示例 17-23 中 的 第 一 个 单元 ， 测 试 请 求 消息 中 传人 有 效 的 码 值 的 场景 。 
示例 17-23: 有 效 码 值 的 单元 测试 


[Fact] 
public class ApplicationKeyActionFilterFixture 


{ 
public void ShouldValidateKey() 


{ 
































var keyVerifier = new Mock<IKeyVerifier>(); 
keyVerifier 
.Setup(k => k.VerifyKey("mykey")) 
-Returns(true); // <1> 


var request = new HttpRequestMessage(); 
request.Headers.Add("X-AuthKey", "mykey"); // <2> 


var actionContext = InitializeActionContext(request); // <3> 


var filter = new ApplicationKeyActionFilter(keyVerifier .Object); 
filter .OnActionExecuting(actionContext); // <4> 


Assert.NuLl(actionContext.Response); // <5> 


} 
} 


private HttpActionContext InitializeActionContext(HttpRequestMessage request) 


{ 


var configuration = new HttpConfiguration(); 


var route = configuration.Routes.MapHttpRoute( 
name: "DefaultApi", 
routeTemplate: "api/{controller}/{id}", 
defaults: new { id = RouteParameter.Optional } 


); 


var routeData = new HttpRouteData(route, 
new HttpRouteValueDictionary 


{ 
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{ "controller", "Issues" } 


); 
request.Properties[HttpPropertyKeys.HttpRouteDataKey] = routeData; 


var controllerContext = new HttpControllerContext(configuration, routeData, 
request); 


var actionContext = new HttpActionContext { 
ControllerContext = controllerContext 


J 


return actionContext; 


} 


这 个 单元 测试 的 第 一 步 <1>， 是 初始 化 IKeyverfier 的 一 个 模拟 或 伪 实 例 ， 这 个 实例 
的 VerifyKey 方法 在 传人 参数 为 mykey 时 返回 true。 第 二 步 <2>， 测 试 创建 了 一 个 新 的 
HTTP 请 求 消息 ， 将 定制 标 头 Xx-AuthkKey 的 值 设置 为 IKeyverifier 实例 预期 的 码 值 。 方 法 
InitializeActionContext 初始 化 了 筛选 器 预期 的 操作 上 下 文 <3>， 其 中 用 到 了 大 量 的 通用 
基础 代码 ， 将 路 由 配置 和 请 求 消息 注入 到 HttpControllerContext 类 的 构造 函数 中 。 最 后 ， 
测试 使 用 完成 初始 化 的 上 下 文 ， 调 用 OnActionExecuting 方法 <4>， 并 对 null 响应 进行 了 
断言 <5:>>。 如 果 这 个 操作 筛选 器 实现 中 没有 出 现 错误 ， 那 么 上 下 文中 不 会 设置 响应 ， 这 个 
测试 就 会 通过 。 

















示例 17-24 将 测试 下 一 个 场景 ， 即 码 值 无 效 并 返回 一 个 状态 码 为 491 (Unauthorized) 的 响应 。 





示例 17-24: 无 效 码 值 的 单元 测试 
[Fact] 
public void ShouldNotValidateKey() 
{ 


var keyVerifier = new Mock<IKeyVerifier>(); 
keyVerifier 
.Setup(k => k.VerifyKey("mykey")) 
.Returns(true); 


var request = new HttpRequestMessage(); 
request.Headers.Add(ApplicationKeyActionFilter.KeyHeaderName, "badkey"); // <1> 


var actionContext = InitializeActionContext(request) ; 


var filter = new ApplicationKeyActionFilter(keyVerifier.Object); 
filter .OnActionExecuting(actionContext) ; 


Assert.NotNull(actionContext.Response); // <2> 
Assert.Equal(HttpStatusCode.Unauthorized, 
actionContext.Response.StatusCode); // <3> 


} 
这 个 测试 与 上 一 个 测试 的 主要 区 别 在 于 ， 请 求 消息 中 设置 的 应 用 程序 码 <1> 与 
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IKeyVerifer 模拟 实例 预期 的 码 值 不 同 。 在 调用 OnActionExecuting 方法 之 后 ， 测 试 执 
行 了 两 个 断言 ， 以 确保 上 下 文中 设置 的 响应 不 为 nutl <2>， 而 且 响 应 的 状态 码 为 461 


(Unauthorized) <3>。 


17.3 对 路 由 进行 单元 测试 


路 由 配置 也 是 你 可 能 需要 在 单元 测试 中 覆盖 的 一 个 方面 。 虽 然 路 由 配置 本 身 不 是 一 个 组 件 ， 
但 是 一 个 不 遵循 党 用 规范 的 复合 路 由 配置 可 能 会 导致 一 些 问题 ， 这 些 问 题 需要 尽早 发 现 ， 
在 实现 部 署 之 前 解决 。 不 幸 的 是 ，ASP.NET Web API 没有 直接 提供 对 路 由 单元 测试 的 任何 
支持 ， 因 此 我 们 需要 使 用 定制 代码 。 定 制 代 码 通常 会 使 用 Web API 基础 结构 中 内 建 的 一 些 
组 件 ， 例 如 ，DefaultHttpControllerSelector 和 ApiControllerActionSelector, Ay2 Æ AY 
HttpRequestMessage 和 路 由 配置 推导 出 控制 器 类 型 和 操作 名 。 具 体 实现 请 见 示 例 17-25。 








F 




















示例 17-25: 测试 路 由 的 一 个 泛 型 方法 
public static class RouteTester 


{ 


public static void TestRoutes(HttpConfiguration configuration, 
HttpRequestMessage request, 
Action<Type, string> callback) 


{ 


var routeData = configuration.Routes.GetRouteData(request) ; 
request.Properties[HttpPropertyKeys.HttpRouteDataKey] = routeData; 


var controllerSelector = new DefaultHttpControllerSelector(configuration);// <1> 
var controllerContext = new HttpControllerContext(configuration, routeData, 
request); 


controllerContext.ControllerDescriptor = controllerSelector 
.SelectController(request); // <2> 


var actionSelector = new ApiControllerActionSelector(); // <3> 


var action = actionSelector.SelectAction(controllerContext).ActionName; // <4> 
var controllerType = controllerContext.ControllerDescriptor 
-ControllerType; // <5> 


callback(controllerType, action); // <5> 
} 
} 


示例 17-25 实现 了 一 个 泛 型 方法 。 这 个 方法 的 参数 是 带 有 路 由 配置 的 paaa a 实 
例 和 一 个 HttpRequestMessage， 使 用 所 选 的 控制 器 类 型 和 操作 名 调用 一 个 回调 函数 。 这 个 方 
法 首先 使 用 参数 中 传 入 的 HttpConfiguration, 实例 化 一 个 DefauLtHttp pn ed 
用 于 决定 控制 器 类 型 <1>;， 然后 选中 这 个 控制 器 ， 并 将 HttpRequestMessage 作为 参数 传人 
<2>。 选 中 控制 器 之 后 ， 这 个 方法 接着 实例 化 一 个 ApiControllerActionSelector， 用 于 获 
取 操 作 名 <3>， 并 在 <4> 和 <5> 中 获得 操作 名 和 控制 器 类 型 。 最 后 ， 这 个 方法 使 用 获得 的 
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控制 器 类 型 和 操作 名 ， 调 用 一 个 回调 函数 <5>。 单 元 测试 可 以 使 用 这 个 回调 函数 执行 断言 。 
具体 用 法 请 见 示例 17-26. 


示例 17-26: 使 用 RouteTester 实现 的 单元 测试 
[Fact] 
public void ShouldRouteToIssueGET( ) 
{ 
var config = new HttpConfiguration(); 
config.Routes.MapHttpRoute(name: "Default", 
routeTempLate: "“api/{controller}/{id}"); // <1> 


var request = new HttpRequestMessage(HttpMethod.Get, 
"http: //www.example.com/api/Issues/1"); // <2> 


RouteTester.TestRoutes(config, request, // <3> 
(controllerType, action) => 
{ 
Assert.Equal(typeof(IssuesController), controllerType) ; 
Assert.Equal("Get", action); 
IDE 
} 





示例 17-26 展示 了 如 何在 单元 测试 中 使 用 RouteTester 类 ， 验 证 路 由 配置 。 这 个 测试 实例 
化 了 一 个 HttpConfiguratiton， 为 其 配置 了 需要 测试 的 路 由 <1>， 以 及 带 有 HTTP 谓词 和 待 
调用 URL 的 HttpRequestMessage <2>。 在 最 后 一 步 ， 测 试 使 用 RouteTester ， 从 配置 和 请 
求实 例 得 到 控制 器 类 型 和 操作 名 。 在 回调 函数 中 ， 测 试 定义 了 断言 ， 将 获得 的 控制 器 类 型 
和 操作 名 与 预期 值 进 行 比 较 <3>。 








17.4 ASP.NET Web API 的 集成 测试 


到 目前 为 止 ， 我 们 讨论 的 都 是 单元 测试 ， 单 元 测试 的 关 广 点 是 在 隔离 环境 下 测试 组 件 。 但 
是 ， 如 果 要 测试 所 有 组 件 在 指定 场景 下 的 相互 协作 ， 该 怎么 做 呢 ?” 这 时 你 需要 用 到 集成 测 
试 。 对 于 Web API， 集 成 测试 更 为 关注 的 是 ， 测 试 从 客户 端 到 服务 的 一 个 完整 的 端 到 端 调 
用 ， 其 中 包括 栈 中 的 所 有 组 件 ， 如 控制 器 、 筛 选 器 、 消 息 处 理 程序 ， 或 者 你 的 Web API iz 
行 时 中 配置 的 任何 其 他 组 件 。 例 如 ， 你 可 能 想 使 用 HttpMessageHandler 支持 基础 身份 验 
证 ， 需 要 进行 集成 测试 ， 从 客户 端 应 用 程序 的 角度 ， 验 证 这 个 处 理 程序 与 已 有 的 控制 器 的 
行为 。 理 想 情况 下 ， 你 也 会 对 这 些 组 件 进行 单元 测试 ， 以 确保 组 件 单独 运行 时 的 行为 是 正 
确 的 。 


JE ASP.NET Web API 中 进行 集成 测试 ， 我 们 要 使 用 HttpCLient， 这 个 类 可 以 在 内 存 托管 
服务 器 中 处 理 请 求 。 使 用 这 种 方法 ， 我 们 无 需 打 开端 口 或 通过 网 络 发 送 消 息 ， 对 于 简化 测 
试 具有 明显 的 优点 。 如 示例 17-27 所 示 ，HttpClient 类 定义 了 几 个 以 HttpMessageHandler 
实例 为 参数 的 构造 函数 。 我 们 在 第 4 章 中 介绍 过 ，HttpServer 类 是 HttpMessageHandler 的 
一 个 实现 ， 因 此 可 以 直接 注入 HttpCLient 实例 中 ， 自 动 处 理 客户 端 在 测试 中 发 送 的 任何 
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示例 17-27: HttpClient 构造 函数 
public class HttpClient : HttpMessageInvoker 
{ 
public HttpClient(); 
public HttpClient(HttpMessageHandler handler); 
public HttpClient(HttpMessageHandler handler, bool disposeHandler ); 


} 


在 集成 测试 中 ， 我 们 可 以 使 用 之 前 实现 的 HttpMessageHandLer， 对 一 个 HttpServer 实例 进 
行 配置 ， 并 将 这 个 HttpServer 传 给 HttpClient， 对 端 到 端的 测试 场景 进行 验证 。 具 体 实现 
请 见 示 例 17-28。 


示例 17-28: 基础 身份 验证 的 集成 测试 
public class BasicAuthenticationIntegrationTests 


{ 
[Fact] 
public ShouldReturn404IfCredentialsNotSpecified() 


{ 








var config = new HttpConfiguration(); 

config.Routes.MapHttpRoute(name: "Default", 
routeTempLate: "“api/{controller}/{action}/{id}", 
defaults: new { id = RouteParameter.Optional }); // <1> 


config.MessageHandlers.Add(new BasicAuthHttpMessageHandler()); // <2> 
var server = new HttpServer(config); 
var client = new HttpClient(server); // <3> 


var task = client.GetAsync("http://test.com/issues"); // <4> 
task.Wait(); 


var response = task.Result; 
Assert.AreEqual(HttpStatusCode.Unauthorized, response.StatusCode); // <5> 


} 
} 


如 示例 17-28 所 示 ， 我 们 仍然 可 以 使 用 单元 测试 框架 进行 集成 测试 的 自动 化 。 我 们 的 测试 
为 一 个 内 存 服务 器 配置 了 默认 路 由 <1> 和 一 个 BasicAuthHttpMessageHandler <2>， 这 个 
处 理 程序 内 部 实现 了 基础 身份 验证 。 测 试 将 这 个 服务 器 注入 到 HttpCLient <3>， 因 此 使 用 
GetAsync 调用 http://test.com/issues 会 将 请 求 发 送 到 这 个 服务 器 <4>。 在 这 个 测试 中 ， 我 们 
没有 在 HttpCLient 中 设置 身份 验证 标 头 ， 因 此 测试 预期 BasicAuthHttpMessageHandler jk 
回 一 个 状态 码 为 464 (Unauthorized) 的 响应 消息 <5>。 身 份 验证 只 是 集成 测试 适用 的 一 个 
场景 ， 但 是 你 可 以 想象 得 到 ， 集 成 测试 也 可 以 扩展 到 任何 需要 多 个 组 件 协作 的 情况 。 
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17.5 “小 结 


测试 驱动 开发 是 驱动 Web API 设计 和 实现 的 极为 有 效 的 工具 。 测 试 驱动 开发 的 副产品 是 反 
Be API 实现 预期 行为 的 单元 测试 。 你 可 以 使 用 这 些 单元 测试 ， 逐 步 对 已 有 代码 进行 改进 。 
当代 码 中 引入 新 变更 时 ， 这 些 测 试 还 可 以 用 来 确保 已 有 功能 没有 遭 到 破坏 ， 并 且 系 统 行为 
依然 符合 预期 。 测 试 驱动 开发 中 有 两 种 常用 实践 : 依赖 注入 和 代码 重 构 。 依 赖 注入 关注 的 
是 ， 如 何 移 除 显 式 依赖 ， 生 成 更 容易 测试 的 代码 ， 代 码 重 构 则 用 于 提高 现 有 代码 的 质量 。 
单元 测试 关注 如 何在 隔离 环境 中 测试 特定 代码 ， 除 此 之 外 ， 你 也 可 以 使 用 集成 测试 ， 对 端 
到 端的 场景 进行 测试 ， 验 证 系统 中 的 不 同 组 件 如 何 进行 交互 。 
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附录 人 





表 A-1: 媒体 类 型 


RERE 





媒体 类 型 描 述 参考 资料 
text/html 用 于 交换 HTML 文档 http://www.iana.org/assignments/media-types/text/html 
application/xhtml+xml 用 于 交换 使 用 格式 良好 的 http://tools.ietf.org/html/rfc3236 


application/xml 
application/json 


application/x-www- 
form-urlencoded 


multipart/mixed 


multipart/form-data 
image/jpeg 
image/gif 

image/png 


image/svg+xml 


application/atom+xml 


application/vnd. 
hal+json 


application/vnd. 
collection+json 


XML 的 HTML 文档 











用 于 交换 JSON 文档 





成 的 单个 正文 
主要 用 于 交换 文件 
用 于 交换 JPEG 文档 
用 于 交换 GIF 文档 
H 
A 


























有 于 交换 PNG 文档 














日 于 交换 Atom 源 


的 数据 
日 于 管理 数据 集合 





ao 


用 于 交换 XML 文档 和 模式 
用 于 交换 表单 键 / 值 数据 


用 于 交换 多 个 数据 集 组 合 而 


日 于 交换 SVG (http://www. 
w3.org/TR/SVGI1/) 文档 


月 
用 于 交换 包含 相关 资源 链接 
能 


http://www.rfc-editor.org/rfc/rfc3023.txt 
http://www. ietf.org/rfc/rfc4627 txt 


http://tools.ietf.org/html/rfc 152 1l#section-7.2.2 


http://tools.ietf.org/html/rfc2388 
http://tools.ietf.org/html/rfc2046 
http://tools.ietf.org/html/rfc2046 
http://tools.ietf.org/html/rfc2083 
http://www.w3.org/TR/S VG/mimereg. html 


http://tools.ietf.org/html/rfc4287 


http://stateless.co/hal_specification.html 


http://amundsen.com/media-types/collection 
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附录 日 





表 B-1: 消息 头 


HTTP 标 头 










































































标 头 描 述 参考 资料 
Cache- 向 请 求 / 响 应 经 过 的 缓存 机 制 给 出 http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache- 
Control 消息 可 缓存 性 的 指令 21#section-7.2 
Connection ”给 出 与 当前 链接 相关 的 选项 ， 不 应 http://tools.ietf.org/html/draft-ietf-httpbis-pl-messaging- 
传 给 代理 21#section-6.1 
Date 说 明 消息 产生 的 日 斯 和 时 间 http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics- 
21#section-8.1.1.2 
Pragma 向 缓存 说 明 应 该 总 是 重新 验证 已 缓 http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache- 
存 的 响应 。 这 个 标 头 是 为 了 回 后 兼 21#section-7.4 
X HTTP 1.0 客户 端 在 HTTP 1.1 
中 由 Cache-Control 标 头 取代 
Transfer- 表明 消息 正文 是 否 为 了 在 发 送 方 和 http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging- 
Encoding 接收 方 之 间 传 输 而 进行 了 转 码 21#section-3.3.1 
Upgrade 如 果 服 务 器 愿意 切换 的 话 ， 人 允许 客 http://tools.ietf.org/html/draft-ietf-httpbis-pl-messaging- 
户 端 指定 希望 使 用 附加 协议 21#section-6.3 
Via 由 网 管 和 代理 使 用 ， 包 含 请 求 时 在 http://tools.ietf.org/html/draft-ietf-httpbis-pl-messaging- 
客户 端 和 服务 器 之 间 ， 以 及 响应 时 21#section-5.7 
在 服务 器 和 客户 端 之 间 的 中 间 协 议 
和 接收 者 。 响 应 TRACE 请 求 的 消 
息 中 的 这 个 标 头 非常 有 用 
Warning 用 于 传递 可 能 无 法 包含 在 消息 自身 http://tools.ietf.org/html/draft-ietf-httpbis-p 1-messaging- 


406 








的 附加 消息 信息 


21#section-5.7 


表 B-2: 请 求 标 头 





标 头 描 OK 参考 资料 
Host 提供 目标 URI 中 的 主机 和 端口 信息 


Max-Forwards 


Expect 


Range 


If-Match 


If-None-Match 


If-Modified- 
Since 


If-Unmodified- 
Since 


If-Range 


Accept 


Accept- 


Charset 


Accept- 
Encoding 


Accept- 


Language 


From 


Referer 


TE 


User -Agent 


Authorization 











用 于 使 用 TRACE 和 OPTION 方法 进行 调 
试 ， 人 允许 客户 端 对 代理 转发 请 求 的 次 数 进 
行 限制 
告知 服务 器 客户 端 预期 的 行为 。 例 如 : 
Expect: 200-Continue 告知 服务 器 ， 客 户 
端 预 期 在 开始 发 送 正 文 之 前 处 理 请 求 
指明 服务 器 应 该 执行 一 个 byte-range 操 
作 ， 只 返回 请 求 的 字 市 

用 于 进行 条 件 请 求 ， 只 有 实体 的 标签 值 匹 
配 资源 的 一 个 或 多 个 表示 时 才 执 行 请 求 

用 于 执行 条 件 请 求 ， 只 有 实体 的 标签 值 不 
匹配 资源 的 一 个 或 多 个 表示 时 才 执 行 请 求 
用 于 执行 条 件 请 求 ， 只 有 当 资 源 在 指定 时 
间 后 经 过 修改 才 执 行 请 求 
用 于 执行 条 件 请 求 ， 只 有 当 资 源 在 指定 时 
间 后 未 经 过 修改 才 执行 请 求 

j 于 执行 条 件 请 求 ， 只 要 实体 标签 匹配 ， 
就 允许 客户 端 获 取 返 回 部 分 表示 

包含 一 个 带 优先 级 的 列表 ， 列 出 可 接受 的 
响应 媒体 类 型 
包含 一 个 带 优先 级 的 列表 ， 列 出 可 接受 的 
响应 字符 编码 
包含 一 个 带 优先 级 的 列表 ， 列 出 可 接受 的 
传输 编码 
包含 一 个 带 优先 级 的 语言 列表 



































a 






























































指明 请 求 发 起 人 的 电子 邮件 地 址 











指明 为 当前 请 求 提 供 目标 URI 的 资源 的 
URI 

指出 除了 “chunked” 之 外 ， 可 接受 的 传 
输 编码 

提供 生成 请 求 的 客户 端的 信息 




















包含 待 访问 域 的 身份 信息 


http://tools.ietf.org/html/draft-ietf-httpbis-p1- 
messaging-21#section-5.4 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 


semantics-21#section-6.1.1 


http://tools.ietf.org/html/draft-ietf-httpbis-p2- 


semantics-2 1#section-6.1.2 


http://tools.ietf.org/html/draft-ietf-httpbis-p5- 
range-21#section-5.4 
http://tools.ietf.org/html/draft-ietf-httpbis-p4- 
conditional-2 1#section-3.1 
http://tools.ietf.org/html/draft-ietf-httpbis-p4- 
conditional-2 1#section-3.2 
http://tools.ietf.org/html/draft-ietf-httpbis-p4- 
conditional-2 1#section-3.3 
http://tools.ietf.org/html/draft-ietf-httpbis-p4- 
conditional-2 1#section-3.4 
http://tools.ietf.org/html/draft-ietf-httpbis-p4- 
conditional-2 1#section-3.5 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-6.3.2 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-6.3.3 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-6.3.4 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-6.3.5 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-6.5.1 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-6.5.2 
http://tools.ietf.org/html/draft-ietf-httpbis-p 1 - 
messaging-2 1#section-4.3 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-6.5.3 
http://tools.ietf.org/html/draft-ietf-httpbis-p7- 
auth-2 1#section-4.1 
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表 B-3: 响应 标 头 





m os H 参考 资料 

Age 间 明 响应 生成 后 经 过 的 时 间 http://tools.ietf.org/html/draft-ietf-httpbis-p6- 
cache-2 1#section-7.1 

Date 间 明 消息 生成 的 日 期 和 时 间 http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-2 1#section-8.1.1.2 

Location 指明 与 这 个 响应 相关 的 一 个 资源 (已 创 http://tools.ietf.org/html/draft-ietf-httpbis-p2- 


Retry-After 


Last-Modified 


ETag 


Vary 


WWW-Authenticate 


Proxy- 
Authenticate 


Accept-Ranges 


Allow 


Server 





建 的 资源 或 客户 端 应 该 重 定 向 到 的 资源 ) 
指明 客户 端 在 向 资源 重 试 请 求 前 应 该 等 
待 的 时 间 。 在 重 定向 响应 中 ， 这 个 标 头 
与 重 定向 URI 相关 

指明 源 服务 器 认为 资源 受到 修改 的 日 期 
和 时 间 
指明 当前 所 选 表示 的 唯一 标识 符 





























肯 明 哪些 字段 用 于 选择 向 客户 端 返回 的 
表示 
指明 一 个 或 多 个 身份 验证 质询 ， 告 知客 


户 端 必须 如 何 向 目标 资源 提供 身份 验证 
各 明 一 个 或 多 个 身份 验证 质询 ， 告 知客 
户 端 必 须 如 何 向 目标 资源 的 代理 提供 身 
份 验证 

指明 客户 端 
可 接受 范围 
指明 目标 资源 支持 哪些 HTTP 方法 




















范围 请 求 时 能 使 用 的 

















包含 源 服务 器 的 服务 器 环境 信息 


表 B-4: 表示 标 头 


semantics-21#section-8.1.1.2 


http://tools.ietf.org/html/draft-ietf-httpbis-p2- 


semantics-21#section-8.1.1.3 


http://tools.ietf.org/html/draft-ietf-httpbis-p4- 
conditional-2 1#section-2.2 
http://tools.ietf.org/html/draft-ietf-httpbis-p4- 
conditional-21#section-2.3 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-21#section-8.2.1 
http://tools.ietf.org/html/draft-ietf-httpbis-p7- 
auth-2 1#section-4.4 
http://tools.ietf.org/html/draft-ietf-httpbis-p7- 
auth-2 1#section-4.2 


http://tools.ietf.org/html/draft-ietf-httpbis-p5- 
range-2 1#section-5.1 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 
semantics-21#section-8.4.1 
http://tools.ietf.org/html/draft-ietf-httpbis-p2- 


semantics-2 1|#section-8.4.2 


























标 关 描 述 参考 资料 

Content-Type 指明 表示 的 媒体 类 型 http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics- 
21#section-3.1.1.5 

Content- 指明 应 用 于 表示 的 内 容 编 码 http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics- 

Encoding 21#section-3.1.2.2 

Content- 指明 当前 表示 的 目标 受众 语言 http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics- 

Language 21#section-3.1.1.5 

Content- 指明 专门 用 于 获取 当前 表示 的 URI http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics- 

Location 21#section-3.1.4.2 

Expires 给 出 响应 过 期 的 日 期 和 时 间 http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache- 
21#section-7.3 
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附录 C 


内 容 协 商 





内 容 协商 (conneg) 有 两 种 类 型 : 主动 式 (proactive) 内 容 协商 和 被 动 式 (reactive) AA 
协商 。 


主动 式 内 容 协商 

如 果 服 务 器 负责 选择 资源 表示 ， 包 含 寻找 最 佳 资源 表示 的 逻辑 ， 在 每 次 请 求 时 执行 ， 那 么 
内 容 协商 就 是 主动 式 的 。 服 务 器 将 可 用 的 表示 与 客户 端 偏 好 或 附加 标 头 进行 匹配 ， 据 此 做 
出 选择 。 客 户 端 通过 之 前 介绍 的 Accept* 请 求 标 头 〈 参 见 表 B-2) 表达 自己 的 偏好 。 这 些 
标 头 都 可 以 发 送 多 个 值 或 范围 ， 以 及 包含 优先 级 的 限定 符 (qualifier， 也 称 为 q-value)。 但 
服务 器 可 以 使 用 附加 字段 ， 如 User-Agent 或 其 他 字段 。 


如 果 服 务 器 认为 ， 客 户 端 发 送 的 信息 不 够 ， 无 法 据 此 做 出 选择 ， 那 么 可 以 使 用 默认 选择 
返回 一 个 状态 码 406 Not Acceptable, 或 者 执行 被 动 式 协商 (参见 下 一 节 )。 一 旦 做 出 先 
择 ， 服 务 器 应 该 向 客户 端 返 回 所 选 的 表示 。 服 务 器 返回 的 响应 应 当 包 含 一 个 Vary 标 头 ， 确 
切 模 明 使 用 了 哪个 标 头 字 眉 做 99 content Location 标 头 ， 给 
出 协商 所 得 内 容 的 URI。 需 要 记 住 的 是 ， 服 务 器 不 受 客户 端 偏 好 的 制约 ， 但 是 应 该 尽量 
试 满足 客户 端 偏 好 。 


图 C-1 展示 了 主动 式 内 容 协商 (proactive negotiation) 的 过 程 。 


























409 

















C-1: 主动 式 内 容 协商 


请 注意 ， 在 图 C-1 中 ， 如 果 客 户 端 没有 发 送 偏好 信息 ， 或 者 服务 器 没有 找到 合适 的 匹配 表示 ， 
服务 器 可 以 自行 做 出 选择 ， 返 回 一 个 默认 表示 ， 或 者 返回 一 个 496 Not Acceptable 响应 。 


Web 浏览 器 通常 使 用 主动 式 内 容 协商 。 当 你 向 服务 器 发 起 请 求 时 ， 浏 览 器 会 发 送 自 己 支 持 
的 一 列 偏好 信息 。 在 一 些 情况 下 ， 浏 览 器 可 能 会 发 送 浏 览 器 插件 支持 的 附加 媒体 类 型 。 下 
面 是 使 用 Chrome 浏览 器 发 送 的 一 个 请 求 ， 请 注意 其 中 由 浏览 器 发 送 的 各 种 Accept 标 头 。 
不 同 的 浏览 器 也 会 有 不 同 的 偏好 。 





GET http://www.yahoo.com/ HTTP/1.1 

Host: www.yahoo.com 

Connection: keep-alive 

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 
Accept-Encoding: gzip,deflate,sdch 

Accept-Language: en-US,en;q=0.8 

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3 


1 — + La] ð 

被 动 式 内 容 协 商 

使 用 被 动 式 内 容 协 商 (reactive negotiation， 也 称 为 代理 驱动 协商 ， 即 agent-driven 
negotiation) ， 选 择 权 就 转 到 客户 端 一 方 。 当 客户 端 向 服务 器 发 送 一 个 资源 请 求 时 ， 服 务 器 
会 返回 一 个 状态 码 为 396 Multiple Choices 的 响应 ， 其 中 包含 一 列表 示 。 客 户 端 根 据 自 己 
的 逻辑 ， 从 这 个 列表 中 进行 选择 。 


图 C-2 描述 了 被 动 式 内 容 协商 的 流程 。 
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GET http://example.com/contacts/1 
Accept: application/json 








返回 选择 列表 


HTTP/1.1 300 multiple choices 
Link: <http://example.com/contacts/1.json>; rel="application/json” 





客户 端 从 列表 进行 选择 ， 访 问 受 保护 资源 





GET http://example.com/contacts/1.json 


客户 端 源 服务 器 


C-2: 被 动 式 内 容 协商 


至 于 包含 选择 的 表示 自身 ，HTTP 协议 的 规范 并 没有 进行 详细 规定 。Mike Amundsen $% 
写 了 一 篇 很 好 的 文章 “Agent-Driven conneg in HTTP” (http://www.amundsen.com/blog/ 
archives/1085) ， 介 绍 被 动 式 内 容 协 商 。 























在 这 篇 文章 中 ，Amundsen 推荐 了 几 种 完全 可 行 的 不 同 实现 方法 ， 一 种 是 返回 一 个 XHTML 
表示 ， 在 其 中 为 每 个 选项 包含 一 条 <a hrefs>， 示 例如 下 : 








HTTP/1.1 300 Multiple Choices 
Host: www.example.org 
Content-Type: application/xhtml 
Content-Length: XXX 


<p> 
Select one: 
</p> 
<a href="/results/fr" hreflang="fr">French</a> 
<a href="/results/en-US" hreflang="en-US">US English</a> 
<a href="/results/de" hreflang="de">German</a> 





另 一 个 方法 是 使 用 Link 标 头 。 这 种 方法 的 优点 是 : Link 是 标准 标 头 ， 任 何 客户 端 都 能 理 
解 。 示 例如 下 : 





HTTP/1.1 300 Multiple Choices 
Host: www.example.org 
Content-Length: 0 
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Link: <http://www.example.org/results/png>; type="image/png", 
<http: //www.example.org/results/jpeg>; type="image/ jpeg", 
<http: //www.example.org/results/gif>;type="image/gif" 

















使 用 已 有 机 制 的 好 处 是 ， 你 可 以 预期 任何 HTTP 客户 端 都 理解 这 种 机 制 。 你 可 以 返回 
application/json 格式 的 内 容 ， 在 其 中 和 嵌入 链接 ， 但 是 除非 客户 端 以 离线 方式 获得 了 这 一 
信息 ， 就 无 法 知道 如 何 解 析 你 返回 的 结果 。 对 此 ， 你 可 以 使 用 profile 链接 标 头 ， 指 向 一 个 
定义 这 种 链接 格式 的 文档 (无 需 创 建新 媒体 类 型 )， 帮 助 客户 端正 确 解析 结果 。 在 下 面 的 
示例 中 ，profile 文档 将 说 明 , 应 使 用 JSON 的 Alternate 列表 解析 响应 内 容 : 






































HTTP/1.1 300 Multiple Choices 

Host: www.example.org 

Content-Type: application/json 

Content-Length : XXX 

Link: <http://www.example.org/profile>; rel="profile" 


{ 
"alternates" : [ 
{"href": "http://www.example.org/results/png", "type":"image/png"}, 
{"href": "http://www.example.org/results/jpeg", "type": "image/jpeg"}, 
{"href", "http://www.example.org/results/gif", "type": "image/gif"} 
] 
} 
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附录 DD 





绥 存 实战 


我 们 已 经 了 解 到 ，HTTP 缓存 涉及 几 个 部 分 。 为 了 说 明 各 部 分 如 何 协同 工作 ， 我 们 来 讨论 
一 个 常见 的 场景 ， 这 个 场景 中 有 两 个 客户 端 、 一 个 HTTP 缓存 以 及 源 服 务 器 。 为 简单 表 
示 ， 图 中 的 响应 将 省 略 正文 和 标 头 。 














首先 ， 如 图 D-1 所 示 ， 客 户 端 A 发 出 一 个 初始 请 求 。 





客户 端 A 缓存 源 服 务 器 
| GET http://example.com/contacts/1 
未 匹配 ， 转 发 请 求 


Accept: application/json 
GET http://example.com/contacts/1 : 


Accept: application/json 


HTTP 1.1 200 OK, ETag: “123456789"” 
Cache-control: max-age=3600, Vary: “Accept” 
Content-type: application/json 


将 响应 返回 客户 端 。、 


: HTTP 1.1 200 OK, ETag: "123456789" 
: Cache-control: max-age=3600, Vary: “Accept” 
: Content-type: application/json, Age: 30 











D-1: 客户 端 A 发 出 初始 GET 请 求 
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(1) 缓存 收 到 请 求 ， 看 到 这 是 一 个 GET 请 求 ， 检 查 是 否 有 已 缓存 的 响应 。 缓 存 未 找到 匹配 的 
响应 ， 因 此 将 请 求 向 源 服务 器 转发 。 

(2) 源 服务 器 生成 响应 ， 响 应 中 包含 ETag 和 max-age 标 头 。 

(3) 缓存 收 到 响应 ， 使 用 请 求 URI 的 散 列 值 和 Accept 标 头 值 ， 将 响应 保存 在 缓存 中 。 

(4 缓存 随 后 将 响应 返回 ， 响 应 中 包含 一 个 附加 的 AGE 标 头 ， 告 诉 客户 端 这 个 表示 的 存在 
时 间 。 

(5) 客户 端 A 收 到 资源 表示 ， 保 存 其 ETag 和 Expires 信息 。 











15 分 钟 之 后 ， 如 图 D-2 所 示 ， 客 户 端 B 向 同一 个 资源 发 起 请 求 。 


GET http://example.com/contacts/1 
Accept: application/json 











将 缓存 的 表示 返回 客户 油 | 


' HTTP 1.1 200 0K, ETag: “123456789  ! 
Cache-control: max-age=3600, Vary: “Accept” + 
Content-type: application/json, Age: 900 


D-2: SP lim B 发 出 初始 GET 请 求 


(1) 缓存 收 到 请 求 ， 检 查 是 否 有 表示 的 副本 。 

(2) 缓 存 使 用 URI 和 Accept 进行 匹配 ， 发 现 表 示 存 在 而 且 有 效 (根据 有 效 期 判断 )， 因 此 
立即 返回 更 新 了 存在 时 间 的 表示 。 

(3) 客户 端 B 收 到 资源 表示 ， 保 存 其 ETag 和 Expires 信息 。 











一 个 小 时 之 后 ， 如 图 D-3 所 示 ， 客 户 端 A 又 向 同一 资源 发 出 一 个 条 件 GET 请 求 ， 请 求 中 包 
含 了 If-None-Match 标 头 。 
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GET http://example.com/contact/1 HTTP/1.1 1 ! 
If-None-Match “123456789" Accept: application/json 





GET http://example.com/contact/1 HTTP/1.1 
If-None-Match "123456789", Accept: application/json 


源 服务 器 验证 ETag 


! 1 HTTP/1.1 304 Not modified, ETag: “123456789” 
! Cache-control: max-age=3600 


HTTP/1.1 304 Not modified 
` Age: 30 i 
P H 


D-3: SP iim A 发 出 条 件 GET 请 求 











(D) 缓存 收 到 请 求 ， 检 查 是 否 存在 表示 副本 。 缓 存 找 到 匹配 的 表示 ， 发 现 表 示 已 经 过 期 ， 随 
后 将 条 件 GET 请 求 转发 给 源 服务 器 ， 以 判断 缓存 保存 的 副本 是 否 依 然 有 效 。 

(2) 源 服务 器 收 到 请 求 ， 断 定 ETAG 依然 有 效 ， 返 回 一 个 状态 为 394 Not Modified 的 响应 ， 
其 中 包含 新 的 max-age。 

(3) 缓存 收 到 响应 ， 向 客户 端 返回 这 个 364 响应 ， 并 在 其 中 包含 更 新 的 表示 存在 时 间 。 


时 间 流 逝 ， 如 图 D-4 所 示 ， 客 户 端 B 向 联系 人 资源 发 出 一 个 条 件 PUT 请 求 ， 更 新 联系 人 
状态 。 




















(缓存 收 到 请 求 ， 发 现 这 个 是 一 个 PUT 请 求 ， 检 查 缓存 是 否 保 存 了 这 个 资源 的 副本 ,以 及 
ETag 是 否 匹 配 。 找 到 副本 后 ， 缓 存 将 这 个 ETag 标记 为 无 效 ， 以 处 理 将 来 的 请 求 。 然 后 
缓存 将 请 求 原样 转发 给 源 服务 器 。 

(2) 服务器 执行 更 新 操作 ， 生 成 带 有 更 新 的 ETag 的 新 响应 。 

(3) 缓存 收 到 响应 ， 保 存 副 本 ， 然 后 将 响应 返回 给 客户 端 B。 
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PUT http://example.com/contact/1 HTTP/1.1 
If-Match “123456789, Accept: application/json 





PUT http://example.com/contact/1 HTTP/1.1 
If-Match 123456789", Accept: application/json 





HTTP 1.1 200 OK, ETag:“123456789” 
Cache-control: max-age=3600, Vary: “Accept” 
Content-type: application/json 


HTTP 1.1 200 OK, ETag: “123456789” 
Cache-control: max-age=3600, Vary: “Accept” 
Content-type: application/json, Age: 30 











图 D-4: 客户 端 B 发 出 条 件 PUT 请 求 
10 分 钟 之 后 ， 如 图 D-5 所 示 ， 客 户 端 A 又 尝试 对 同一 资源 进行 条 件 PUT 操作 。 





PUT http://example.com/contact/1 HTTP 1.1 
If-Match: 123456789", Accept: application/json 





HTTP/1.1 409 Conflict 











图 D-5: SP iim A 发 出 条 件 PUT 请 求 


(1) 缓存 收 到 请 求 并 检查 缓存 内 容 ， 没 有 找到 所 请 求 的 ETag, KAXA ETag 之 前 已 经 更 新 。 
(2) 缓存 向 客户 端 返回 一 个 409 Conflict， 告 知客 户 端 这 个 ETag 已 经 失效 。 
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附录 E 


身份 验证 工作 流 





在 客户 端 到 源 服务 器 的 工作 流 中 ， 客 户 端 需要 向 源 服务 器 验证 自己 的 身份 (参见 图 E-1)。 











HTTP/1.1 401 Unauthorized 
WWW-Authenticate: Basic realm="contacts” 





GET http://example.com/contacts/1 HTTP 1.1 
Authorization: Basic QWxhZGRpbjpvcGVulHNIc2FtZQ== 











图 E-1: 客户 端 向 源 服务 器 验证 自己 的 身份 
客户 端 尝试 访问 源 服务 器 上 的 一 个 受 保护 资源 。 因 为 资源 是 受 保护 的 ， 服 务 器 会 通过 401 
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Unauthorized 响应 ， 向 客户 端 发 回 一 个 质询 。 这 个 响应 带 有 一 个 WWW-Authenticate 标 头 
(参见 表 B-3) ， 其 中 包含 了 一 个 或 多 个 质询 ， 客 户 端 必须 对 这 些 质询 做 出 响应 ， 才 能 访问 
受 保护 资源 。 


客户 端 随后 向 资源 发 回 请 求 ， 请 求 中 提供 了 带 有 所 需 身份 信息 的 Authorization 标 头 。 








在 客户 端 到 代理 的 工作 流 中 ， 客 户 端 通过 安全 代理 访问 资源 ， 客 户 端 必 须 向 这 个 安全 代理 
验证 自己 的 身份 。 图 E-2 展示 了 这 一 过 程 。 








Proxy-Authenticate: Basic realm="contacts” 





GET http://example.com/contacts/1 
Proxy-Authenticate: Basic QWxhZGRpbjpvcGVulHNIc2FtZQ== 





HTTP/1.1 407 Proxy Authentication Required 


-上 


GET http://example.com/contacts/1 
— 











图 E-2: 客户 端 向 代理 验证 自己 的 身份 


客户 端 尝 试 通过 一 个 需要 身份 验证 的 代理 ， 访 问 一 个 受 保护 资源 。 代 理 收 到 请 求 后 ， 通 过 
407 Proxy Authentication Required 响应 ， 向 客户 端 发 送 质询 。 这 个 响应 包含 一 个 Proxy- 
Authenticate 标 头 〈 参 见 表 B-3)， 其 中 包含 了 访问 这 个 代理 自身 的 一 个 或 多 个 质询 ， 客 户 
端 随后 发 回 请 求 ， 请 求 中 提供 了 带 有 所 需 身 份 信息 的 Proxy-Authorization 标 头 。 在 通过 
代理 的 身份 验证 之 后 ， 如 果 用 户 尝试 访问 的 资源 是 受 保护 的 ， 那 么 还 会 进行 源 服务 器 身份 
验证 。 图 E-3 展示 了 这 一 过 程 ， 代 理 身份 验证 结束 之 后 ， 源 服务 器 发 回 质 询 响应 。 
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GET http://example.com/contacts/1 
Proxy-Authenticate: Basic QWxhZGRpbjpvcGVulHNIc2FtZQ== 
一 





GET http://example.com/contacts/1 
o 


ES 


HTTP/1.1 401 Unauthorized 
WWW-Authenticate: Basic realm="contacts” 


GET http://example.com/contacts/1 HTTP 1.1 
Authorization: Basic }WxhZGRpbjpvcGVulHNIc2FtZQ== 


图 E-3: 客户 端 向 源 服务 器 验证 自己 的 身份 
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附录 FF 
application/issue+json 媒 体 类 型 规范 





在 很 多 复杂 工程 项 目的 生命 周期 ， 以 及 这 些 产 品 随后 的 维护 中 ， 我 们 需要 跟踪 项 目 相 关 问 
题 的 发 现 和 解决 过 程 。 这 个 媒体 类 型 规范 描述 了 一 个 交互 性 门槛 很 低 的 文档 格式 。 当 前 的 
规范 是 一 个 最 简 的 定义 ， 预 期 未 来 会 加 入 更 多 的 功能 。 


一 、 ea 
标记 约定 
这 个 文档 中 的 关键 字 (MUST、MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD 


NOT, RECOMMENDED, MAY 和 OPTIONAL) 定 X 4n RFC 2119 ( 参见 http://tools.ietf.org/html/ 
rfc2119), 


Ad H 
问题 文档 
示例 F-1 所 示 的 问题 文档 使 用 RFC 4627 中 描述 的 格式 ， 文 档 的 媒体 类 型 为 appLcation/ 


issue+json, 


























示例 F-1: 最 小 的 问题 文档 
{ 


} 
问题 文档 可 以 包含 表 F-1 中 列 出 的 属性 。 


"title" : "This is a very simple issue" 
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表 F-1: 属性 语义 








属性 名 描 述 

id 问题 的 唯一 数字 标识 符 

title 问题 的 简短 文字 概述 (必须 具备 ) 
description 问题 的 详细 描述 

status 问题 状态 的 文本 表示 ， 值 为 : open 或 closed 


issue+json 也 使 用 链接 支持 超 媒体 ， 链 接 遵循 RFC 5988 (参见 http://tools.ietf.org/html/ 


rfc5988) 中 描述 的 链接 语义 。 链 接 由 一 个 名 为 Links 的 数组 中 的 一 组 对 象 定义 。 


安全 性 考虑 


issue+json 具有 一 些 所 有 JSON 内 容 类 型 都 有 的 安全 问题 。 要 获得 更 多 的 信息 ， 请 参考 
RFC 4627 的 第 6 节 (参见 http:Wtools.ietf.org/html/rfc4627#section-6) 。issue+json 不 提供 可 
执行 内 容 。issue+json 文档 中 包含 的 信息 不 要 求 隐私 服务 或 完整 性 服务 。 


交互 性 考虑 














IANA 考 虑 


这 个 规范 定义 了 一 个 新 的 互联 网 媒体 类 型 (RFC 6838, http://tools.ietf.org/html/rfc6838) : 


Type name: application 
Subtype name: issue+json 
Required parameters: None 
Optional parameters: None; unrecognised parameters should be ignored 
Encoding considerations: Same as [RFC4627] 
Security considerations: see [this document] 
Interoperability considerations: None. 
Published specification: [this document] 
Applications that use this media type: HTTP 
Additional information: 
Magic number(s): n/a 
File extension(s): n/a 
Macintosh file type code(s): n/a 
Person & email address to contact for further information: 
Darrel Miller <darrel@tavis.ca> 
Intended usage: COMMON 
Restrictions on usage: None. 
Author: Darrel Miller <darrel@tavis.ca> 
Change controller: IESG 


无 法 识别 的 文档 内 容 应 该 忽略 ， 文 档 不 应 该 因为 有 无 法 识别 的 内 容 而 被 视 为 无 效 。 





application/issuetjson 媒 体 类 型 规范 
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Mi SR G 


公 钥 加 密 和 证 书 





1976 年 ，Whitfield Diffie 和 Martin Hellman 提出 公 钥 加 客 ， 为 大 规模 的 安全 通信 系统 带 来 
了 一 大 突破 。Diffie 和 Hellman 提出 的 主要 想法 是 ， 由 每 个 实体 生成 和 使 用 一 个 或 多 个 键 
对 ， 每 个 键 对 由 一 个 私 钥 和 一 个 公 钥 组 成 。 私 钥 必 须 保密 ， 永 远 不 需要 发 送 给 其 他 通信 
方 。 而 公 钥 可 以 公开 分 发 ， 没 有 任何 保密 要 求 。 这 些 分 发 的 公 钼 随后 可 以 由 第 三 方 使 用 ， 
执行 如 下 操作 


。 发 送 加 密 消 息 ， 这 些 消息 只 能 由 私 钥 持 有 者 解密 ， 
。 验证 签名 ， 只 能 由 私 钥 持 有 者 产生 。 








公 钥 加 密 也 称 为 非 对 称 加 密 (asymmetric cryptography) ， 因 为 其 机 制 使 用 了 两 个 密 钥 ， 其 
保密 要 求 不 同 ， 而 且 用 途 不 同 : 


。 私 钥 必须 保密 ， 用 于 解密 消息 ， 或 者 产生 数字 签名 ， 
。 公 钥 可 以 公开 分 发 ， 没 有 任何 保密 要 求 ， 用 于 加 密 消息 或 验证 签名 。 


公 钥 加 密 与 经 典 加密 不 同 。 经 典 加 密 也 称 为 对 称 加 密 ， 使 用 同一 个 密 钥 进行 所 有 的 操作 
(例如 :加 密 和 解密 )， 这 个 密 钥 必须 保密 。 目 前 所 知 的 非 对 称 机 制 ， 性 能 都 不 如 相应 的 对 
称 机 制 ， 因 此 人 们 经 常 使 用 混合 技术 。 例 如 ， 在 TLS 中 ， 担 手 协议 使 用 非 对 称 机 制 ， 建 立 
一 组 保密 的 对 称 会 话 密 钥 ， 然 后 记录 协议 使 用 这 组 密 钥 ， 使 用 对 称 机 制 ， 保 护 大 部 分 的 交 
换 消息 。 

但 是 ， 公 铀 加 密 带 来 了 一 个 新 问题 : 公 钥 身份 验证 。 尽 管 公 钥 可 以 公开 分 发 ， 但 是 接收 方 
必须 具有 某 些 安全 方法 ， 得 知 这 些 密 钥 属于 谁 (B: 谁 是 相关 私 钥 的 持 有 者 )。 如 果 不 能 
正确 对 公 钥 进行 身份 验证 ， 公 和 钥 接 收 方 就 容易 遭 到 MTM 攻击 。 在 中 间 人 攻击 中 ， 攻 击 者 
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将 一 个 实体 公 负 替换 为 自己 的 密 钥 。 攻 击 者 拥有 和 所 使 用 公 钥 相 关 的 私 钥 ， 从 而 可 以 解密 
发 送 给 这 个 实体 的 所 有 消息 


对 公 钥 进行 身份 验证 的 一 个 常用 方法 是 使 用 公 钼 证 书 。 公 钼 证 书 是 将 一 个 公 钥 绑 定 到 一 个 
主体 的 声明 ， 由 CA (证 书 授权 机 构 ) 颁发 和 签名 。 这 些 CA 是 第 三 方 机 构 ， 在 其 之 上 有 
一 组 实体 承认 其 权威 性 和 验证 这 种 绑 定 的 能 力 。 也 就 是 说 ，CA 检查 与 一 个 公 钥 相 关 的 密 
钥 的 持 有 者 是 否 也 为 一 个 名 字 的 所 有 者 (例如 : DNS 名 )。 


为 了 介绍 得 更 为 具体 ， 让 我 们 来 看 一 个 例子 : 一 个 客户 端 执 行 一 个 HTTP 请 求 ， 访 问 位 
于 https://webapi-book.blob.core.windows.net/ 的 资源 。 这 个 资源 URI 使 用 https 方案 ， 因 此 
HTTP 请 求 消息 必须 通过 受 TLS 或 SSL 保护 的 连接 发 送 。 安 全 连接 通过 握手 协议 建立 。 客 
户 端 首先 向 服务 器 发 送 一 个 client hello 消息 ， 其 中 包含 客户 端 支持 的 加 密 机 制 。 服 务 器 
做 出 响应 ， 返 回 一 个 server hello 消息 ， 其 中 包含 选中 的 加 密 机 制 ， 并 返回 一 个 包含 服务 
器 证 书 的 certificate 消息 。 证 书 详情 请 见 图 G-1。 





























General | Details | Certification Path 


Show | <All> 





[Signature hash algorithm sha: 
issuer 


Digital Signature, Key Encipherme... 
Client Authentication (1.3.6.1.5.5... y 





Learn more about certificate details 


























图 G-1: *.blob.core.windows.net 证 书 





这 个 证 书 遵循 X.509 规范 (参见 http:Wwww.itu.intrec/T-REC-X.509) ， 由 几 个 字段 组 成 ， 比 
如 下 面 几 个 。 


。 公 钥 (public key) 字段 ， 其 中 包含 服务 器 的 公 铀 。 

。 主题 (subject) 字段 ， 其 中 包含 服务 器 名 。 在 我 们 的 示例 中 ，subject 字段 值 是 带 有 通 配 
符 的 字符 串 *.blob.core.windows.net, 

。 MARA (issuer) 字段 ， 包 含 证 书 颁发 实体 的 名 字 (CA 名 )。 在 我 们 的 示例 中 ，issuer 
字段 值 为 Microsoft Secure Server Authority, 





这 个 证 书 还 包含 其 颁发 者 产生 的 一 个 签名 ， 因 此 可 以 通过 非 安 全 渠道 存储 和 分 发 。 
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接收 到 证 书 之 后 ， 客 户 端 可 以 使 用 证 书 中 的 公 钥 ， 加 密 一 个 保密 的 随机 种 子 值 ， 将 其 发 送 
给 服务 器 。 这 个 随机 种 子 是 一 个 保密 的 值 ， 客 户 端 和 服务 器 都 将 使 用 这 个 值 ， 派 生出 保护 
交换 字 布 流 的 会 话 密 钥 。 但 是 ， 客 户 端 首先 必须 确保 (同时 还 要 满足 其 他 条 件 ) : 





























。 证 书 的 主题 与 httpsURI 的 主机 名 相符 ; 

。 证 书 在 从 服务 器 到 客户 端 传输 的 过 程 中 没有 遭 到 自 改 (握手 协议 使 用 的 连接 是 不 受 保护 
HY) ; 

。 颁发 证 书 的 CA (在 之 前 的 示例 中 ， 即 Microsoft Secure Server Authority) 受到 信任 ,在 
这 种 情况 下 有 能 力 执行 公 钥 和 实体 名 之 间 的 绑 定 。 
































最 后 ， 客 户 端 通常 会 将 证 书 的 颁发 者 字段 与 一 个 信任 库 (trust store， 其 中 包含 受信 任 的 颁 
发 者 名 及 其 公 钥 ) 进行 比较 ， 完 成 验证 。 第 二 个 任务 是 ， 使 用 证 书 颁发 者 的 公 钥 (也 保存 
在 信任 库 中 ) 验证 证 书 的 签名 。 











信任 库 (trust store) 通常 由 自 颁发 证 书 组 成 ， 每 个 证 书包 含 一 个 受到 信任 的 CA 名 及 其 公 
钥 。 这 些 自 颁 发 的 证 书 由 CA 创建 ， 通 过 受到 认证 的 机 制 ， 离 线 分 发 。 将 一 个 自 颁发 的 证 
书 添加 到 这 个 信任 库 ， 意 味 着 使 用 证 书 的 实体 : 








。 决定 信任 这 个 自 颁发 证 书 的 主题 字段 标识 的 CA 一 一 也 就 是 说 ， 认 为 这 个 CA 颁发 的 每 
个 证 书 都 包含 一 个 真实 的 公 钥 绑 定 ; 
。 已 经 验证 了 这 个 自 颁发 证 书 所 含 的 公 钥 确实 属于 这 个 CA。 























我 们 特别 强调 最 后 一 个 要 求 ， 因 为 一 个 自 签名 的 证 书 不 足以 将 一 个 公 钥 绑 定 到 一 个 名 字 ， 
这 个 验证 必须 通过 别 的 途径 完成 。 














图 G-2 展示 了 我 们 刚才 所 描述 的 模型 的 一 个 示例 。 





subject: CAO 
CA0-key 











验证 example.net 


名 和 私 钥 所 有 权 




















subject: example.net 















在 TLS 握 手 上 使 








server-key 

















图 G-2: 直接 由 一 个 受信 任 CA 颁发 证 书 
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情 如 下 。 


ap 


在 图 G-2 中 发 生 的 





lig 


。 CAO 验证 了 ， 运 行 服务 器 的 实体 是 与 server-key 相关 的 私 钥 的 持 有 者 ， 并 且 是 域名 
example.net 的 合法 所 有 者 ， 然 后 颁发 CS 证 书 。 

。 客户 端 信任 CAO 的 认证 能 力 ， 因 此 在 检查 了 证 书信 息 (也 就 是 其 公 钥 ) 的 正确 性 之 后 ， 
将 CAO 的 自 颁发 证 书 安装 到 自己 的 信任 库 中 。 

。 在 TLS 握手 协议 中 ， 客 户 端 收 到 CS 证 书 ， 通 过 检查 (1) 证 书 由 一 个 受信 任 的 CA 颁发 ， 
(2) 通过 CA 公 钥 成 功 验证 证 书签 名 ， 对 证 书 进行 验证 。 然 后 ， 客 户 端 使 用 server-key 
加 密 一 个 保密 种 子 ，( 据 CAO 称 ) 这 个 加 密 信息 只 能 由 example.net 解密 。 
































CA 颁发 证 书 的 操作 ， 应 该 在 对 认证 信息 进行 安全 验证 之 后 进行 ， 特 别 是 对 公 钥 到 名 字 绑 
定 的 验证 。 通 常 ，CA 在 一 个 称 为 认证 实践 声明 (Certification Practice Statements, http:// 
cybertrust.omniroot.com/repository/) 的 文档 中 描述 这 一 安全 验证 过 程 。 根 据 名 字 范 围 
(DNS 名 、 电 子 邮件 和 居民 身份 号 码 ) 的 不 同 ， 认 证 代价 可 能 很 高 〈 例 如， 验证 官方 记录 ， 
确保 一 个 实体 是 一 个 注册 名 的 所 有 者 )， 或 者 难以 执行 (CA 与 命名 机 构 没 有 任何 关系 )。 
因此 ，CA 可 以 将 认证 功能 委托 给 其 他 CA， 这些 CA 称 为 中 间 (intermediate) CA 或 下 属 
(subordinate) CA。 这 种 委托 通过 颁发 一 个 证 书 完成 。 这 个 证 书 的 颁发 者 是 直接 受到 信任 
的 CA， 主题 是 中 间 CA。 这 个 证 书 有 两 个 作用 ， 除 了 将 中 间 CA 名 绑 定 到 其 公 钥 ， 还 声明 
了 这 个 颁发 者 的 一 部 分 认证 功能 委托 给 这 个 中 间 CA。 












































subject: CAO 
CA0-key 









将 验证 权力 
委托 给 CA1 









issuer: CAO 


subject: CA1 




















验证 example.net 名 


和 私 钥 所 有 权 









Subject: example.net 


















在 TLS 握 手 上 使 月 


Hserver-key 














G-3: 中 间 认 证 机 构 和 认证 路 径 
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图 G-3 展示 了 这 一 扩展 模型 。 


。 CAO 直接 受到 客户 端 信任 ， 通 常 称 为 根 (root) CA. CAO 通过 颁发 中 间 证 书 C1， 将 其 
认证 功能 委托 给 CAL 

e CA1， 而 非 CA0， 验 证 了 运行 服务 器 的 实体 是 与 server-key 相关 的 私 钥 的 持 有 者 ， 并 
且 是 域名 example.net 的 合法 所 有 者 。 








在 这 个 模型 中 ， 服 务 器 证 书 验 证 要 求 构 建 一 个 证 书 链 (certificate chain) 一 一 由 从 直接 受到 
信任 的 CO 证书 (位 于 信任 库 中 ) 一 一 到 服务 器 证 书 的 所 有 证 书 组 成 ， 途 经 中 间 证 书 Cl 





再 回 到 我 们 的 具体 场景 ， 图 G-4 展示 了 *.blob.core.windows.net 认证 路 径 ， 这 个 路 径 由 两 个 
中 间 CA 组 成 。 只 有 根 CA (GTE Cyber Trust Global Root) 受到 客户 端的 直接 信任 。 但 是 ， 
根 CA 将 自己 的 认证 权力 委托 给 了 Microsoft Internet Authority, Microsoft Internet Authority 
又 将 其 委托 给 Microsoft Secure Server Authority。 颁 发 服务 器 证 书 的 是 最 后 一 个 CA. 























General Details | Certification Path 


Certification path 
E GTE CyberTrust Global Root 
ER] Microsoft Internet Authority 
ql Microsoft Secure Server Authority 
*.blo ndows.net 


core.W 














View Certificate 


Certificate status: 


This certificate is OK. 


Learn more about certification paths 
































图 G-4: 服务 器 证 书 路 径 
在 Windows 系统 中 ， 证 书 通过 库 进 行 管理 。 图 G-5 展示 了 一 个 Windows 证 书库 。 这 些 证 
书库 按 位 置 (当前 用 户 ， 本 地 计算 机 ) 进行 组 织 ， 具 有 特殊 的 语义 。 


。 私有 (Personal) Æ: 也 保存 了 与 库 中 证 书 公 钥 相 关 的 密 钥 。 
。 受信 任 根 证 书 颁 发 机 构 (Trusted Root Certification Authorities) 库 : 包含 可 以 用 作 认 证 
路 径 根 的 受信 任 证 书 。 
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Hy 





o 


中 间 证 书 颁 发 机 构 (Intermediate Certification Authorities) Æ: 包含 不 是 直接 受到 信任 ， 
但 可 以 用 来 构建 认证 路 径 的 CA 证 








a Gl Certifica 


p 





> & Certifica 





I Console Root 


4 © Personal 

4 国 Trusted Root Certification Authorities 
E Certificates 

© Enterprise Trust 

E Intermediate Certification Authorities 

© Active Directory User Object 

E Trusted Publishers 

© Untrusted Certificates 

© Third- 

E Trusted People 

© Client Authentication Issuers 

E Other People 

b 国 Certificate Enrollment Requests 

国 Smart Card Trusted Roots 


tes - Current User 


Party Root Certification Authorities 





tes (Local Computer) 








B G-5; Windows 证 书库 


$35 Fz 


“4 Windows 证 书 管理 系统 需 





LAR 


要 验证 一 个 证 





区 时 ， 只 有 当 认 证 路 径 的 根 位 于 受信 任 根 证 书 


颁发 机 构 库 中 时 ， 系 统 才 认 为 这 个 认证 路 径 是 有 效 的 。 在 向 受信 任 根 证 书 颁发 机 构 库 添加 


证 书 时 ， 你 必须 格外 谨慎， 因为 这 个 库 的 内 容 定 义 了 谁 有 权 颁 发 有 效 证 
Fiddler 工具 在 这 个 信任 库 中 加 入 了 一 个 证 





书 ， 还 可 以 伪装 成 远程 服务 器 ， 


拦截 HTTPS 消息 。 











当 
at 


过 在 这 里 用 于 开发 和 调试 ， 用 途 是 


撤销 


5 的 
Fa 
Er ah HY o 





B. lán, wR 





B, ABARAT EAA EAA ARS a EA AC TE 
这 种 做 法 其 实 就 是 MITM 攻击 ， 


只 不 


证 书信 息 的 有 效 性 可 能 随 着 时 间 发 生 改变 。 换 句 话 说 ， 如 果 一 个 攻击 者 获得 了 一 个 实体 的 








私 钥 ， 那 么 相关 的 公 负 就 不 应 该 











了 被 使 用 。 
为 此 ， 你 可 以 使 用 一 个 包含 无 效 (撤销 ) 证 





BHJ CRL (Certificate 


撤销 清单 )。 例 如 ， 在 之 前 的 示例 中 ，*.blob.core.windows.net 证 
点 (CLR distribution point) 字段 ， 字 段 值 为 一 个 CRL URI (http://mscrl.microsoft.com/pki/ 


mscorp/crl/Microsoft%20Secure%20Server%20Authority(8).crl1)。 当 进行 证 
撤销 清单 ， 检 查证 





URI 可 以 用 于 获取 证 


另 一 个 方法 是 使 用 OCSP (Online Certificate Status Protocol, WEJ 


是 否 已 经 撤销 。 











Revocation List， 证 书 
区 包含 一 个 CRL 分 发 








验证 时 ， 这 个 





BB 状态 协议 )， 由 客户 
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端 直接 向 CA 询问 证 书 的 当前 状态 ， 以 检查 证 书 当前 是 否 有 效 。 证 书 的 验证 过 程 应 该 包含 
这 些 撤销 检查 中 的 一 种 。 





如 果 需 要 了 解 X.509 证 书 在 互联 网 中 使 用 的 更 多 信息 ， 包 括 认 证 路 径 的 构建 和 验证 细节 ， 
我 们 推荐 你 阅读 PKIX IETF 工作 组 提出 的 一 组 规范 ， 即 RFC 5280, 


Py %, > ya s 
创建 测试 密 钥 和 证 书 
在 开发 使 用 TLS 协议 的 客户 端 和 服务 器 时 ， 如 果 能 有 一 组 用 于 测试 的 密 钥 和 证 书 ， 对 我 们 
会 很 有 帮助 。 在 随后 的 段落 中 ， 我 们 将 介绍 如 何 使 用 一 组 Windows 命令 行 工 具 ， 创 建 测试 
密 钥 和 证 书 。 但 是 ， 在 开始 之 前 ， 我 们 应 该 强调 一 点 : 这 些 窗 钥 和 证 书 只 用 于 测试 用 途 ， 
请 不 要 在 生产 环境 中 使 用 。 











第 一 步 ， 使 用 makecert 工具 ， 创 建 一 个 根 证 书 颁发 机 构 。， 





makecert -r -n“CN=Demo Certification Authority;0=Web API Book” ^ 
-sv webapibook-ca.pvk ^ 
-len 2048 -e 01/01/2020 -cy authority webapibook-ca.cer 











其 中 的 -r 选项 告诉 makecert 生成 一 个 自 签 名 的 证 书 一 一 也 就 是 说 ， 使 用 与 证 书 中 所 含 公 
钥 相 关 的 密 钥 进 行 签名 的 证 书 。 这 个 证 书 将 用 作 认 证 路 径 的 根 。 

















这 个 证 书 颁发 机 构 的 义 .500 名 为 CN=Demo Certification Authority;0=Web API Book， 其 中 
CN 和 0 都 是 名 字 属 性 : CN 代表 常用 名 (common name), 0 代表 组 织 (organization)。 私 钥 
将 使 用 由 给 定 密 码 生 成 的 密 钥 进行 加 密 ， 保 存在 文件 webapibook-ca.pvk 中 。 这 个 私 钥 将 用 
于 对 颁发 的 每 个 证 书 进行 签名 。 














第 二 步 ， 为 一 个 虚拟 的 服务 器 www.example.net 生成 一 个 非 对 称 密 钥 对 和 证 书 。 这 个 任务 
也 可 以 使 用 makecert 工具 完成 。 





makecert.exe -iv webapibook-ca.pvk -ic webapibook-ca.cer -n “CN=www.example.net” ^ 
-sv example.pvk -len 2048 -e 01/01/2020 ^ 
-sky exchange example.cer -eku 1.3.6.1.5.5.7.3.1 


pvk2pfx.exe -pvk example.pvk -spc example.cer -pfx example.pfx 


这 个 证 书 由 上 一 步 生成 的 CA 发 布 ， 因 此 makecert 要 同时 使 用 这 个 CA 的 证 书 (进行 命 
名 ) 和 CA 私 钥 (进行 签名 )。 甚 中 的 -eku 1.3.6.1.5.5.7.3.1 选项 给 生成 的 证 书 添加 了 一 
个 增强 密 钥 使 用 扩展 (enhanced key usage extension) ， 说 明 这 个 证 书 可 以 用 于 TLS 服务 器 
身份 验证 。 














注 1: makecert 是 .NET 框架 工具 。 
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Pyk 文件 包含 服务 器 的 私 钥 ，.cer 文件 包含 服务 器 的 证 书 ， 证 书 中 包含 其 公 钥 。 第 二 步 执 
行 的 最 后 一 行使 用 pvk2pfx.exe 工具 ， 将 私 钥 和 证 书 都 封装 在 一 个 .pfx (个 人 信息 conan 

personal information exchange) 文件 中 。 这 个 .pfx 文件 使 用 PKCS#12 交互 性 格式 ， 进 行 密 
码 资料 〈 例 如 : 私 钥 和 证 书 ) 的 交换 ， 是 Windows 中 进行 数字 证 书 和 密 钥 交换 最 常用 的 
格式 。 











一 步 ， 我 们 要 为 两 位 密码 学 中 大 名 时 上 易 的 虚构 人 物 Alice 和 Bob (参见 http://bit.ly/ 
porns 生成 客户 端 证 书 。 





makecert.exe -iv webapibook-ca.pvk -ic webapibook-ca.cer ^ 
-n "CN=ALlice;0=Web API book fictional characters" ^ 
-sv alice.pvk -len 2048 -e 01/01/2020 -sky exchange ^ 
alice.cer -eku 1.3.6.1.5.5.7.3.2 

pvk2pfx.exe -pvk alice.pvk -spc alice.cer -pfx alice.pfx 


makecert.exe -iv webapibook-ca.pvk -ic webapibook-ca.cer ^ 
-n "CN=Bob;0=Web API book fictional characters" ^ 
-pe -sv bob.pvk -len 2048 -e 01/01/2020 -sky exchange ^ 
bob.cer -eku 1.3.6.1.5.5.7.3.2 

pvk2pfx.exe -pvk bob.pvk -spc bob.cer -pfx bob.pfx 


这 个 过 程 与 生成 服务 器 证 书 和 密 钥 的 过 程 相 似 ， 但 有 一 个 区 别 : 生成 的 证 书 带 有 
1.3.6.1.5.5.7.3.2 扩展 ， 说 明 可 以 用 于 TLS 客户 端 一 方 的 身份 验证 。 





eee 我 们 应 该 生成 了 两 类 文件 。 文 件 webapibook-ca.cer 包含 CA 证 书 ， 而 信任 
个 实体 进行 认证 的 各 方 都 应 该 使 用 这 个 文件 。 在 Windows 中 ， 用 户 做 出 这 个 信任 决定 ， 
pany 个 证书 加 入 到 用 户 的 受信 任 根 证 书 颁发 机 构 库 中 。.pfx 文件 包含 通信 各 方 (www. 


example.net、Alice 和 Bob) 的 证 书 和 密 钥 ， 应 该 安装 在 各 方 的 私有 证 书库 中 。 
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ASPNET Web API 设 计 


如 何 为 浏览 器 和 移动 设备 等 多 客户 端 设 计 和 构建 可 演化 Web API? AB 
以 ASPNET Web API 框 架 为 例 ， 系 统 介 绍 了 相关 的 理论 和 工具 ， 让 读者 全 
面 掌 握 设计 和 实现 可 演化 Web API 的 技术 。 


本 书 主要 面向 有 经 验 的 .NET 开 发 人 员 。 不 过 ， 书 中 关于 Web API 基 础 理论 
和 设计 的 内 容 同样 适用 于 Java、Ruby、PHP 和 Node 等 开发 者 。 


E 深入 理解 HTTP， 以 及 API 开 发 的 概念 和 风格 
国 ASP.NET Web API 基 础 知识 ， 包 括 该 框架 处 理 HTTP 请 求 的 生命 周期 
E 以 “问题 跟踪 ”API 为 例 ， 探 讨 用 Collection+JSON 实 现 超 媒体 支持 


= 采取 BDD (行为 驱动 开发 ) 方式 开发 ASP.NET Web API， 实 现 和 
改进 应 用 


E 探索 可 响应 变化 的 客户 端 技术 ， 使 客户 端 便于 使 用 超 媒体 APl 


E 全 面 介 绍 ASP.NET Web API 的 内 部 工作 机 制 ， 包 括 安 全 性 和 可 测 
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南 ， 帮 助人 们 使 用 ASP.NET 
Web API 构 建 坚 实 的 系统 ， 融 
合 了 ASP.NET Web API 团 队 的 
经 验 与 软件 业界 多 年 的 专业 积 
一 一 Scott Guthrie 
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想 读 ， 原 因 有 二 。 首 先 ， KRY 
前 的 工作 中 涉及 为 应 用 设计 API 
以 使 之 与 多 种 系统 交互 。 其 次 ， 
是 因为 本 书 的 一 位 作者 Glenn 
Block， 我 认识 他 有 段 时 间 了 ， 
我 见 过 他 ， 与 他 有 过 对 话 ， 读 
了 他 的 大 量 博文 ， 我 确定 本 书 不 
会 让 人 失望 ， 而 事实 证 明确 实 
如 此 。” 
—Joseph Guadagno 
亚利桑那 Southeast Valley NET 
用 户 组 创始 人 
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